Api-blueprint: Aset eksternal

Dibuat pada 14 Agu 2013  ·  43Komentar  ·  Sumber: apiaryio/api-blueprint

Tambahkan kemungkinan untuk menggunakan tautan penurunan harga di mana pun aset diharapkan (misalnya, badan muatan atau skema).

Language Idea Feature
Sumber
picture zdne
👍12

Komentar yang paling membantu

Saya tertarik dengan kemampuan ini, dan idealnya ingin ditambahkan lebih cepat daripada nanti.

Kasus penggunaan khusus kami adalah untuk mendokumentasikan API di mana badan permintaan dan tanggapan adalah struktur biner yang diproduksi oleh Apache Avro . Untuk permintaan/tanggapan ini, kami ingin agar "Skema" menjadi tautan ke file definisi skema Avro, atau dokumen HTML yang dihasilkan yang menjelaskan skema Avro tersebut. Mungkin terlihat seperti ini:

## POST /myresource
Creates a new myresource.

+ Request (application/vnd.example.myresource+avro)
    + Schema:
        [MyResource.avsc](http://docs.example.com/avro/myresource.avsc)
+ Response 201 (application/vnd.example.myresource+avro)
    + Schema:
        [MyResource.avsc](http://docs.example.com/avro/myresource.avsc)
picture davidmc24 pada 21 Okt 2013
👍5

Semua 43 komentar

Saya tertarik dengan kemampuan ini, dan idealnya ingin ditambahkan lebih cepat daripada nanti.

Kasus penggunaan khusus kami adalah untuk mendokumentasikan API di mana badan permintaan dan tanggapan adalah struktur biner yang diproduksi oleh Apache Avro . Untuk permintaan/tanggapan ini, kami ingin agar "Skema" menjadi tautan ke file definisi skema Avro, atau dokumen HTML yang dihasilkan yang menjelaskan skema Avro tersebut. Mungkin terlihat seperti ini:

## POST /myresource
Creates a new myresource.

+ Request (application/vnd.example.myresource+avro)
    + Schema:
        [MyResource.avsc](http://docs.example.com/avro/myresource.avsc)
+ Response 201 (application/vnd.example.myresource+avro)
    + Schema:
        [MyResource.avsc](http://docs.example.com/avro/myresource.avsc)
davidmc24 picture davidmc24 pada 21 Okt 2013
👍5

:+1:

mhurne picture mhurne pada 21 Okt 2013

@mhurne @davidmc24 Sudahkah Anda memikirkan representasi fitur ini di AST? Apakah Anda ingin melihat hyperlink di AST atau parser cetak biru harus mampu mengambil url target dan menyematkan kontennya ke AST?

netmilk picture netmilk pada 21 Okt 2013

Harapan saya adalah bahwa AST akan berisi hyperlink, bukan konten hyperlink tersebut. Mungkin berguna bagi AST untuk "mengetahui" bahwa itu adalah hyperlink yang bertentangan dengan konten langsung, sehingga tautan dapat dibuat dalam dokumentasi HTML, misalnya.

Dalam kasus di mana Anda memilih untuk mengeksternalisasi skema dari API, kemungkinan karena skema terlalu besar untuk masuk akal untuk dimasukkan ke dalam dokumentasi API, skema digunakan oleh beberapa API dan memiliki dokumentasi otoritatifnya sendiri, atau skema adalah format yang tidak sesuai untuk penyematan. Sementara contoh-contoh itu khusus untuk skema, saya berharap alasan serupa berlaku untuk jenis muatan lainnya.

davidmc24 picture davidmc24 pada 21 Okt 2013

@davidmc24

Saya menyukainya. Jika itu hanya hyperlink, itu mungkin cukup mudah untuk diterapkan di parser.

Namun tantangan yang lebih besar datang dengan perubahan yang diperlukan pada AST dan jenis medianya

Mungkin untuk sesuatu seperti ini:

{
  "name": "<name>",
  "description": "<description>",
  "headers": {
    "<header>": {
      "value": "<header value>"
    }
  },
  "body": {
    "content": "<body>",
    "href": "<uri>"
  },
  "schema": {
    "content": "<schema>",
    "href": "<uri>"
  }
}
zdne picture zdne pada 22 Okt 2013

Yap, itulah AST yang saya pertimbangkan.

davidmc24 picture davidmc24 pada 22 Okt 2013

Selain itu tambahkan sintaks tambahan untuk aset eksternal yang akan disematkan (bukan hanya direferensikan-linked) oleh Drafter apiaryio/snowcrash#57

:[file.json](path/to/file.json)

atau

=[file.json](path/to/file.json)

Atau menggunakan Mardkown _implicit link name_:

:[path/to/file.json]()

atau

=[path/to/file.json]()
zdne picture zdne pada 31 Jan 2014
👍3

Halo,
Berikut ini kasus penggunaan lain untuk memiliki tautan eksternal: Saya ingin menautkan definisi/deskripsi atribut di API ke definisi masing-masing dalam glosarium utama kami yang digunakan oleh semua dokumentasi. Saya pikir ini membuka pintu untuk menjaga semua dokumentasi tetap up to date dan sinkron. Jika tidak, saya harus memperbarui dokumen API. secara terpisah, yang meninggalkan ruang untuk definisi tidak sinkron.

angie2014 picture angie2014 pada 28 Mei 2014

Penurunan harga adalah keluarga ekstensi yang sebagian besar kompatibel secara tidak nyaman, jadi saya tidak yakin, tetapi satu-satunya kasus yang dapat saya pikirkan di mana sintaks seperti tautan sebenarnya berarti "menyematkan bukan referensi" adalah sintaks gambar (menggunakan ! sigil) : ![Alt text](/path/to/image.jpg "Optional Title") , yang merupakan bagian dari spesifikasi asli Gruber . Saran Z di atas semuanya melanggar struktur ini (nama file di tempat yang salah). Bukankah lebih baik untuk menyesuaikan diri, cukup gunakan sigil baru pada sintaks yang sudah ada?

jrep picture jrep pada 30 Mei 2014

Poin bagus @jrep !

Bukankah lebih baik untuk menyesuaikan diri, cukup gunakan sigil baru pada sintaks yang sudah ada?

Itu adalah tujuan saya.

Menurut Gruber berikut ini harus mencapai tujuan yang sama:

[label](path/to/image.png)

[alt text][label2]
[label2]: path/to/image.png

[label3][]
[label3]: path/to/image.png

Di mana label , alt text dan label3 , secara teori, tidak ada tetapi kemudian elemen tidak terlihat setelah rendering.

Saya kira poin saya dengan

=[path/to/file.json]()

Seharusnya

=[path/to/file.json][]

di mana label adalah URL sebenarnya, jadi definisi lengkap yang tepat (sehingga penurunan harga dirender dengan benar) adalah:

=[path/to/file.json][]
[path/to/file.json]: path/to/file.json

Sekarang jelas akan membosankan untuk menulis:

[path/to/file.json]: path/to/file.json

Pertanyaannya adalah – haruskah ini (mendefinisikan label) diasumsikan secara implisit oleh parser? Atau haruskah kita meminta penulis cetak biru untuk menggunakan sintaks [alt text](URL) ?

zdne picture zdne pada 2 Jun 2014

Tidak bisakah kita menggunakan bagian alt/label untuk benar-benar _mendeskripsikan apa itu aset_ sehingga tautannya dapat dibaca manusia? Menulis sesuatu seperti =[file.json](path/to/file.json) tampaknya tidak perlu membosankan, tetapi =[Schema for notes](path/to/file.json) tampaknya baik-baik saja bagi saya - mendorong penulis cetak biru untuk membuat cetak biru kurang samar bagi pembaca. Sebenarnya, aset bisa hilang atau terkadang tidak jelas apa sebenarnya yang terkait. Atribut alt pada gambar diciptakan persis untuk kasus ini, saya pikir.

Jika seseorang ingin melewati ini dan mengabaikan praktik terbaik dalam mendeskripsikan aset dengan cara ini, dia selalu dapat meletakkan teks tiruan di sana (seperti yang telah disebutkan file.json ).

Saya menggunakan sintaks = hanya sebagai contoh, hal yang sama akan berlaku untuk ! .

honzajavorek picture honzajavorek pada 2 Jun 2014

Saya merasa kita harus mendukung penurunan harga dengan sigil ekstra terlepas dari sintaks yang digunakan – baik itu tautan langsung, label eksplisit atau implisit.

Jika kita menyetujui ini, hanya dua pertanyaan yang tersisa:

  1. Sigil apa yang digunakan
  2. Gaya apa yang akan kita gunakan dalam contoh / tutorial

Perhatikan bahwa menurut saya label seperti Schema for notes in

=[Schema for notes](path/to/file.json)

adalah dup juga karena paling sering Anda akan menggunakannya di bagian skema dari sumber daya Notes ...

misalnya:

# Notes [/notes]
## GET 
+ Response 200
    + Body
         ...
    + Schema
        =[Schema for Notes](path/to/file.json)

Pikiran?

zdne picture zdne pada 2 Jun 2014

Saya mendukung semua varian standar, tetapi ini:

=[jalur/ke/file.json][]
[path/ke/file.json]: path/ke/file.json

... bukan bagaimana saya memahami definisi Gruber. Sebaliknya, saya setuju dengan honzajavorek: hal-hal di [] pertama dalam beberapa hal adalah tag yang dapat dibaca manusia, bukan duplikat teks tautan yang berlebihan dan melelahkan. Jadi, meskipun tampaknya valid secara sintaksis untuk memasukkan jalur di sana, itu (a) aneh, dan (b) tidak membantu.

Jika maksudnya adalah "semua formulir tautan yang valid-Gruber, dengan sigil baru," maka saya menyukai semantik itu tetapi menyarankan contoh yang kurang mengejutkan (dari jenis honzajavorek dan saya telah menyarankan).

jrep picture jrep pada 3 Jun 2014

@jrep @honzajavorek Saya setuju.

zdne picture zdne pada 3 Jun 2014

Saya pikir sulit untuk membandingkan penyertaan aset dengan pola yang ada untuk gambar atau tautan. Bukankah itu sebenarnya kombinasi dari keduanya?

Masalah dengan analogi sintaks gambar adalah bahwa di dunia gambar, teks alt itu penting, mereka biasanya tidak menduplikasi dalam konteks tertentu dan tidak ada yang ingin benar-benar menulis ![img.jpg](/path/to/img.jpg) - hanya sistem manajemen konten dan "malas" orang melakukan ini. Memerlukan teks alternatif adalah mengajarkan kebiasaan yang baik.

Tetapi aset tidak selalu membutuhkan teks alternatif, itu benar. Seperti yang disebutkan @zdne , mereka akan selalu digunakan dalam konteks sedemikian rupa sehingga akan sangat jelas apa yang terjadi di sini. Saya setuju dengan itu. Masalahnya adalah, satu-satunya analogi yang dapat saya pikirkan adalah tautan tanpa label:

[Google](http://www.google.com) versus...

  • <http://www.google.com> ( Gruber )
  • http://www.google.com (kenyataan penurunan harga hari ini, kurasa)

Jika kita membutuhkan sesuatu yang hibrid, sebut saja "sintaks tautan otomatis untuk gambar", dan kami ingin mematuhi Gruber sebanyak yang kami bisa, kami menginginkan sesuatu seperti berikut:

  • =[Alternative text about assets](/dev/null) semua orang akrab dengan ini, ini harus menjadi contoh (_itu seperti gambar, masuk akal!_ muncul di kepala orang)
  • =[Alternative text about assets][id] untuk memasukkan aset yang sama ke beberapa tempat
  • =</dev/null> atau <=/dev/null> sintaks autolink (_...bagaimana sintaks autolink terlihat untuk gambar?_), tidak ada yang tahu versi autolink Gruber (karena link dikonversi secara otomatis di mana-mana, bahkan tanpa < s dan > s), tetapi jika mereka benar-benar tidak membutuhkan teks alternatif dan mereka terganggu olehnya, orang dapat belajar menggunakan ini

Sekali lagi, menggunakan = hanya sebagai contoh. Menurut pendapat saya itu akan menjadi solusi yang paling mudah dibaca dan/atau setidaknya Gruber-ish. Misalnya, saya menganggap

[label3][]
[label3]: path/to/image.png

menjadi agak samar bagi saya sebagai pembaca dan tidak mengikuti realitas penggunaan penurunan harga yang ada. Saya bahkan tidak tahu tentang kemungkinan seperti itu, saya pikir pemasangan harus dilakukan oleh pasangan kedua tanda kurung. (Namun, saya sepenuhnya menyadari paragraf terakhir ini sangat subjektif).

honzajavorek picture honzajavorek pada 3 Jun 2014

@zdne : untuk sigil: Saya tidak terlalu peduli, tetapi = kita semua gunakan tampaknya baik-baik saja.

@zdne : Saya mengakui bahwa kemungkinan besar teks =[IN HERE](schema.json) berlebihan untuk penggunaan Cetak Biru apa pun yang dapat saya pikirkan. Hanya brainstorming, di sini, tetapi bagaimana jika kita memanfaatkan redundansi itu untuk menyederhanakan tata bahasa? Artinya, ganti

# Notes [/notes]
## GET 
+ Response 200
    + Body
         ...
    + Schema
        =[Schema for Notes](path/to/file.json)

dengan

# Notes [/notes]
## GET 
+ Response 200
    + Body
         ...
    + =[Schema for Notes](path/to/file.json)

@honzajavorek : apakah Anda benar-benar menyarankan agar Blueprint mengizinkan/mengamankan string "/ dev/null" di tempat-tempat itu? Atau apakah itu hanya tempat penampung?

Saya juga tidak pernah menggunakan "tautan referensi", tetapi saya tidak akan keberatan dengan Blueprint yang meneruskannya.

jrep picture jrep pada 3 Jun 2014

@jrep saya menggunakan /dev/null hanya sebagai pengganti :)

Menggunakan tautan langsung di header bagian tidak terlihat buruk sama sekali, sebenarnya! Tentu saja, ini hanya pandangan pertama, aku tidak terlalu memikirkan apa kekurangannya, tapi... pada pandangan pertama sepertinya menarik bagiku.

honzajavorek picture honzajavorek pada 3 Jun 2014

@jrep saya suka.

Mengambilnya lebih jauh

# Notes [/notes]
## GET 
+ Response 200
    + =[Body](path/to/body.json)
    + =[Schema](path/to/schema.json)
zdne picture zdne pada 4 Jun 2014

Kemampuan untuk membagi file menjadi file terpisah dan kemudian mengimpornya akan sangat berguna untuk API verbose yang panjang.

Untuk sementara saya mengelola proyek cetak biru saya dengan gerutuan. Saya menggunakan grunt-import dan file index.source.apib sebagian besar terdiri dari <strong i="7">@import</strong> "/include/section.apib";

Kemudian yang saya lakukan adalah menjalankan grunt watch dan segera setelah saya menyimpan file apa pun, grunt akan mengkompilasi ulang file index.source.apib ke dalam 'index.apib' - yang juga sedang diawasi oleh aglio, menyegarkan browser saya ke tunjukkan rendernya secara real time.

Dibutuhkan 5 menit untuk setup, tapi itu membuat hidup jauh lebih menyenangkan! :+1:

alexborisov picture alexborisov pada 30 Agu 2014

@alexborisov itu cukup rapi! Terima kasih untuk berbagi. Seperti yang telah saya katakan (di tempat lain) – kami telah memulai pekerjaan pada alat harness parser yang pada akhirnya akan menangani hal ini.

Juga, untuk apa nilainya, berikut adalah skrip yang menyusun beberapa cetak biru menjadi satu dan menerbitkannya menggunakan permata klien Apiary https://Gist.github.com/danvine/11087404

zdne picture zdne pada 1 Sep 2014

@alexborisov , itu solusi yang sangat cerdas! Apakah Anda (atau siapa pun yang menonton masalah ini) mengetahui apakah ada mitra Gulp untuk mengimpor kasar? Tegukan yang saya temukan semua target JS dan html docs.

skawaguchi picture skawaguchi pada 24 Nov 2014

@skawaguchi Anda dapat menggunakan -file-include dan membuat tugas tegukan untuk menonton json Anda dan membangun api. Satu-satunya downside adalah bahwa Anda harus memiliki api.source.md untuk menghasilkan api.md Anda, tapi IMO itu harga yang kecil untuk membayar.

ghost picture ghost pada 24 Feb 2015

Juga untuk apa nilainya, checkout Hercule @jamesramsay – https://github.com/jamesramsay/hercule

zdne picture zdne pada 25 Feb 2015

Terima kasih @zdne atas penyebutannya. Saya memiliki tantangan serupa saat menulis dokumentasi API dan kami telah menggunakan Hercule secara internal selama 3 bulan terakhir.

Hercule menggunakan pola {{filename.md}} untuk dimasukkan.

Kami memiliki sejumlah konteks API untuk berbagai jenis konsumen API yang memiliki sumber daya yang hampir sama dan kami ingin mengurangi duplikasi antara dokumen yang berbeda. Jadi, kami juga telah memperluas sintaks ini untuk juga mendukung:

{{entity.json links:role-links.json}}

{
  "id": 123,
  "name": "example",
  "links": {
    {{links}}
  }
}

Placeholder {{links}} kemudian dapat memiliki file target yang ditentukan oleh salah satu file induknya. Kami menemukan ini berguna untuk skema besar yang hampir sama.

jamesramsay picture jamesramsay pada 26 Feb 2015

@jamesramsay

Saya hanya ingin tahu mengapa menggunakan sintaks {{link}} alih-alih [<placeholder>](link) Markdown sendiri? seperti yang dibahas di atas. Sebagai contoh:

=[gist](gist.apib)

atau

:[gist](gist.apib)

itu akan bekerja dengan cara yang sama, itu akan dirender secara wajar sebagai penurunan harga, sehingga Anda akan dapat menavigasi melalui tautan, dan Anda dapat menggunakan sintaks yang jauh lebih kaya seperti [placeholder][] dengan opsi tautan `[placeholder]...

zdne picture zdne pada 27 Feb 2015

@zdne ini adalah saran yang sangat bagus! Sayang sekali saya tidak melihat utas ini 6 bulan yang lalu.

Sintaks {{link}} didasarkan pada sintaks transklusi MultiMarkdown 4 . Itu berhasil dan saya tidak menemukan sintaks baru.

Saat itu saya juga melihat aplikasi Marked ( <<[link] ) dan beberapa kompiler penurunan harga lainnya.

Dengan keuntungan dapat mengeklik tautan saat melihat dokumentasi sumber di Github dan meningkatkan konsistensi dengan nuansa Penurunan Harga, saya telah memperbarui hercule untuk menggunakan :[gist](gist.apib) . Jika ada yang ingin mencobanya, ada di NPM.

jamesramsay picture jamesramsay pada 4 Mar 2015

Hai teman-teman, saya menggunakan API Blueprint dengan aglio untuk proyek internal kami, dan karena API Blueprint tidak mendukung file termasuk saat ini, aglio mengimplementasikannya dengan sintaks <!-- include(filename.json) --> , berkat fitur ini kami dapat membagi request/resposne Data JSON dari dokumen API dengan jelas, tetapi ketika kami mengatur file data JSON yang terpisah, kami merasa masih kekurangan cara yang tepat untuk menggunakan kembali bagian yang sama, misalnya, kami memiliki user_model.json :

{
    "username": "alice",
    "comments": [
        {
            "id": 1,
            "content": "hello"
        }
    ]
}

dan comment_model.json :

{
    "id": 1,
    "content": "hello"
}

bagian komentar di user_model.json adalah dan harus selalu sama dengan comment_model.json , jika ada mekanisme yang memungkinkan file JSON untuk menyertakan satu sama lain, akan sangat mudah untuk menjaga konsistensinya, jadi bahwa jika model pujian diubah, kita tidak perlu mengubahnya di mana-mana.

Saya mempertimbangkannya untuk beberapa waktu dan mencoba membuat sintaks untuk mendukung file JSON termasuk, inilah upaya saya,
a sertakan sytanx dengan implementasi Python: https://github.com/reorx/json_include

Sintaksnya akan seperti, dalam kasus sebelumnya:

{
    "username": "alice",
    "comments": [
        {
            "...": "include(commend_model.json)"
        }
    ]
}

menggunakan { "...": "include(commend_model.json)"} untuk mewakili file termasuk ke commend_model.json .

Ini bukan kasus khusus untuk API Blueprint, tetapi sesuatu yang agak umum, untuk mencoba memikirkan JSON itu sendiri dengan kemampuan include, yang menurut saya juga dapat digunakan dalam API Blueprint.

Silakan lihat dan berikan beberapa saran, saat ini json-include berfungsi dengan baik di beberapa proyek saya, setiap pemikiran tentang itu akan sangat dihargai, karena saya tidak dapat memutuskan apakah itu baik dan bermakna atau tidak sendirian: )

reorx picture reorx pada 28 Apr 2015

Hai @reorx ! Terima kasih telah berbagi ide. Baru-baru ini kami telah meluncurkan (beta) MSON – sintaks untuk mendeskripsikan data (tidak hanya) di API Blueprint. Idenya adalah, Anda menggambarkan data Anda sekali dan kemudian meminta serialisasi ke dalam format yang berbeda.

Menggunakan contoh Anda berfungsi seperti ini:

# Data Structures

## User 
- username: alice
- comments (array[Comment])

## Comment
- id: 1
- content: hello

dan kemudian Anda dapat meminta untuk merendernya sebagai JSON:

# Resource [/r]
## Retrieve [GET]
+ Response (application/json)
    + Attributes (User)

Bagaimana menurutmu? Apakah ini akan membantu Anda?

zdne picture zdne pada 28 Apr 2015

Apakah fitur ini ada di jalur pipa? Itu akan sangat menyenangkan bagi kami.
Kami menggunakan Cetak Biru untuk menjelaskan metode, tetapi skema JSON kami dihosting secara terpisah. Kami harus menyertakan skema sebagai tautan dalam deskripsi metode, karena skema tersebut tidak didukung di bawah elemen permintaan/tanggapan saat ini.
Sebenarnya hal yang paling ideal adalah jika kita dapat "menyertakan" halaman web skema JSON menggunakan tautan di bawah elemen permintaan/tanggapan, tetapi itu harus dimuat dengan malas, untuk menghindari melakukan ratusan penyertaan ketika halaman dokumentasi dimuat.

jonathancrosmer picture jonathancrosmer pada 20 Agu 2015

Saya pikir fakta bahwa Anda tidak dapat menyertakan referensi eksternal untuk contoh badan permintaan/tanggapan dan file skema definisi adalah salah satu _sangat_ kelemahan besar yang dimiliki Blueprint sehubungan dengan bahasa definisi API lainnya.

mariusor picture mariusor pada 17 Nov 2015

+1

moon0326 picture moon0326 pada 21 Nov 2015

@jonathancrosmer @lpbm @moon0326

periksa https://github.com/jamesramsay/hercule terutama

https://github.com/jamesramsay/hercule/blob/master/examples/api-blueprint/Gist-fox.apib

dan

https://github.com/jamesramsay/hercule/blob/master/examples/api-blueprint/blueprint/gists.md

apakah ini akan berhasil untuk Anda?

zdne picture zdne pada 24 Nov 2015

@zdne saya tidak mengikuti.

Kedua contoh itu tidak banyak menunjukkan. Apa yang saya lihat?

moon0326 picture moon0326 pada 24 Nov 2015

@zdne : ya, selama itu memungkinkan penyertaan semua jenis sumber daya eksternal, baik itu .md/.apib atau xml, json itu bagus.

Apakah itu sesuatu yang akan diterapkan oleh Peternakan, atau apakah pesan Anda menyarankan kami untuk menggunakan hercule sebelum berkomitmen ke peternakan lebah?

mariusor picture mariusor pada 24 Nov 2015

Kembali yang lalu saya telah menyiapkan daftar solusi untuk membagi cetak biru menjadi beberapa file (dan menggunakan aset eksternal): https://Gist.github.com/zdne/137396a1c2d45f75b306

@jamesramsay mengumpulkan alat Hercule yang luar biasa yang mengimplementasikan sintaks yang ingin saya gunakan untuk membagi cetak biru menjadi beberapa bagian.

Sedangkan untuk aset eksternal. Hercule bekerja di sana juga meskipun saya tidak yakin apakah ini harus menjadi sintaks terakhir dan menyarankan penggunaan di dalam gumpalan JSON terutama melalui prisma MSON .

Namun demikian jika Anda tidak bergantung pada pengeditan di dalam Apiary, Anda dapat menggunakan Hercule hari ini untuk mendapatkan sebagian besar fungsi ini.

Apakah itu sesuatu yang akan diterapkan oleh Apiary?

Kami ingin menerapkan beberapa transklusi berdasarkan sintaks :[](url) , ya. Tangkapannya di sini adalah editor Apiary dan implementasi "sistem file". Sampai saat itu Anda harus menggunakan Hercule dan mendorong file gabungan ke Apiary.

Apakah ini memperjelas?

zdne picture zdne pada 25 Nov 2015
👍1

Tangkapan di sini adalah editor Apiary dan implementasi "sistem file"

Mungkin Anda bisa menghindarinya dengan menggunakan URL?

mariusor picture mariusor pada 25 Nov 2015

Untuk mengambil dokumen mungkin ya tetapi tidak untuk mengedit.

zdne picture zdne pada 25 Nov 2015

Saat ini kami memiliki cetak biru Apiary yang disimpan di repositori git kami, yang terhubung ke Apiary. Cetak biru memiliki banyak tautan ke server internal yang menghosting skema JSON kami.
Saya kira dengan solusi ini kita akan memiliki file penurunan harga asli, kemudian menggunakan kait Git atau sesuatu untuk menjalankan transklusi dan mengkomit hasilnya sebagai cetak biru yang disinkronkan. Kedengarannya seperti itu bisa berhasil; sedikit kerumitan untuk mengatur proses transklusi, tetapi akan licin jika berhasil, jadi saya akan memeriksanya. Terima kasih!

jonathancrosmer picture jonathancrosmer pada 25 Nov 2015

@lpbm Hercule mendukung

@jonathancrosmer tepat - kami melakukan hal serupa menggunakan Jenkins di lingkungan CI internal kami. Di Adslot, setiap kali komit didorong ke cabang mana pun, bersama dengan pengujian unit, kami mengkompilasi Cetak Biru API dengan Hercule, dan kemudian meneruskannya ke dredd. Jika semuanya lulus, sebagai bagian dari tugas penerapan, kita dapat secara opsional mendorong ke Apiary. Kami awalnya mendorong langsung ke Apiary segera setelah perubahan dibuat pada dokumen API, tetapi kami menemukan ini terkadang menyebabkan masalah ketika kami mengerjakan rilis yang lebih besar dengan sakelar fitur dan semacamnya, jadi kami sekarang menerapkannya bersama aplikasi.

jamesramsay picture jamesramsay pada 25 Nov 2015

Bagaimana dengan mengizinkan URI biasa untuk ditentukan? Perender dapat memutuskan apakah akan merender URI ke tautan atau menyertakan isinya dalam output dokumentasi. Ini juga menyelamatkan kita dari kesulitan karena harus berurusan dengan rasa penurunan harga yang berbeda.

bartfeenstra picture bartfeenstra pada 20 Mei 2016

Bagaimana dengan mengizinkan URI biasa untuk ditentukan?

Seharusnya begitu. [label](URI) harus digunakan untuk transklusi dan juga render dengan baik. Perbedaannya adalah kita perlu menandai jika untuk alat transklusi maka :[label](URI)

zdne picture zdne pada 9 Jun 2016

Hai,

Apakah ada berita tentang ini?
Saya pikir skema dan contoh harus dipisahkan dari bagian utama dokumentasi api, sehingga dapat digunakan oleh server dan/atau klien untuk validasi dan pengujian unit. Tautan baik-baik saja.

Bersulang,

Tamas

smil2k picture smil2k pada 11 Des 2017

Halo semuanya, saya minta maaf karena datang terlambat dan membuka kembali dan menggali barang-barang lama. Jika ini bukan tempat yang tepat, mohon maafkan saya. Tapi, melakukan penelitian untuk mengembangkan tiruan cetak biru saya telah menemukan diskusi ini dan ini adalah yang paling dekat yang bisa saya temukan sampai sekarang.

Saya berjuang untuk membagi tanggapan saya berdasarkan model :(. Apakah mungkin untuk merujuk model ke folder yang berbeda?
Saya ingin memiliki di dalam folder cetak biru saya semua permintaan saya, dan, misalnya ke dalam folder model terpisah semua model entitas saya (MSON/MD/JSON/file apa pun, yang cocok) untuk menggunakannya kembali ke dalam respons yang berbeda dengan mudah. Adakah yang berhasil melakukan ini?

clucasalcantara picture clucasalcantara pada 5 Agu 2018
Apakah halaman ini membantu?
0 / 5 - 0 peringkat

Masalah terkait

mootpointer picture mootpointer  ·  4Komentar
bennettellis picture bennettellis  ·  7Komentar
annappropriate picture annappropriate  ·  5Komentar
alronlam picture alronlam  ·  4Komentar
agougousis picture agougousis  ·  8Komentar