Api-blueprint: Modularitas

Untuk situasi di mana ada sejumlah besar API, mungkin di bawah kendali kelompok yang berbeda dalam sebuah perusahaan, ini akan menjadi anugerah mutlak.

@rurounijones hanya untuk klarifikasi fitur ini dimaksudkan "Untuk dapat membagi satu deskripsi API menjadi beberapa file".

Adakah yang punya pemikiran tentang ini? Sesuai komentar saya sebelumnya di Drafter https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28538342

Opsinya adalah menambahkan beberapa fasilitas include / require di bagian atas cetak biru atau cukup ambil semua cetak biru dari direktori dan gabungkan bersama-sama.

Pikiran?

Penggabungannya lebih sederhana tetapi saya merasa membutuhkan akan lebih mudah digunakan karena Anda mungkin ingin meminta, lalu menambahkan sesuatu yang lain setelahnya.

Apakah ini hanya menyisipkan konten file secara membabi buta seolah-olah itu didefinisikan dalam paten, atau akankah ada semacam pembatasan pada konten file (mis. bisakah mereka memiliki header yaml sendiri? Konflik dengan parent yaml?) Saya merasa bahwa tidak ada batasan yang lebih baik tetapi saya pikir saya akan membicarakannya.

@zdne

Pertama, saya memiliki sistem yang belum sempurna untuk mengelola ini dengan Grunt, menggunakan penggabungan file sederhana. Cetak biru kami menjadi tidak dapat diatur, dan ini adalah cara cepat dan kotor untuk membaginya menjadi beberapa file (sebagai catatan, banyak file yang sewenang-wenang, karena mereka digabungkan oleh urutan sistem file). Saya memposting Gruntfile saya dengan penjelasan singkat di sini .

Mengingat bahwa rangkaiannya sangat sederhana untuk menggulung diri sendiri, masuk akal bagi saya bahwa alat "resmi" harus lebih kuat. Saya telah memikirkan lebih banyak tentang ini, mencoba melakukan penelitian tentang bagaimana ini ditangani oleh sistem lain.

1. Sertakan/Perlu
   
   
   
   • Termasuk akan dilakukan di bagian atas file, dan bagian dari file akan direferensikan di dalamnya. Saya pikir ini membutuhkan sistem referensi yang lebih kuat daripada sintaks [Model Reference][] saat ini. Idealnya setiap simpul dalam file yang disertakan akan dapat dialamatkan - jadi seseorang mungkin memiliki sesuatu seperti [github.Users.'Create A User'][] atau [github][POST /users] atau sesuatu. (Mungkin juga memerlukan awalan seperti = ). Apakah ada cara yang lebih baik untuk mereferensikan node tertentu di AST selain nama atau url+metode?
   
   
   • Mengingat bahwa Anda memiliki cara yang baik untuk mendereferensi konten node, ini dapat dilakukan dengan C Preprocessor yang akan datang dengan banyak fitur tambahan tanpa biaya tambahan.
   
   
2. Sistem templating/Transklusi
   
   
   
   • Non-markdown - Template akan ditulis dalam bahasa template yang terpisah, jadi file template tidak akan dapat diuraikan oleh snowcrash. Contoh dari sesuatu seperti ini adalah grunt-readme , yang sepertinya bisa bekerja di luar kotak untuk membuat templat file cetak biru.
   
   
   • Penurunan harga - Ini akan menjadi seperti sintaks =[]() atau :[]() yang kita diskusikan pada masalah drafter. Itu masih akan menjadi penurunan harga yang valid dan dapat diuraikan oleh snowcrash.
   
   
3. Keduanya
   
   
   
   • Mengingat bahwa Anda mendefinisikan sintaks untuk referensi node ( [github]['Create A User'] ) dan transklusi langsung ( :[/github.md](/github.md) ), sepertinya Anda dapat dengan mudah memiliki keduanya. Mungkin mereka dapat memiliki sintaks umum yang sama seperti :[]() dan pengurai menentukan apakah itu simpul atau referensi file.
   
   

Ada pemikiran tentang ini? Apakah saya melewatkan beberapa opsi/alat? Saya agak condong ke opsi "keduanya" dengan sintaks umum untuk transklusi dan dereferensi simpul, tapi mungkin itu sedikit banyak.

Mengingat bahwa rangkaiannya sangat sederhana untuk menggulung diri Anda sendiri, masuk akal bagi saya bahwa alat "resmi" harus lebih kuat

Yah akhirnya mungkin ya, tapi saya ingin tidak mendesainnya secara berlebihan dan meluncurkan sesuatu yang ramping dan sederhana dalam mengemis.

Melihat masalah yang ada, masalah yang perlu ditangani, terutama:

1. Aset (eksternal) yang direferensikan - #20 dan seperti yang dibahas di https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071
2. Memisahkan cetak biru menjadi bagian-bagian logis yang lebih mudah dikelola

Untuk tujuan pemisahan, saya hanya akan mempertimbangkan Grup Sumber Daya atau Sumber Daya (misalnya bukan tindakan, contoh transaksi, atau permintaan). Setidaknya di awal.

Iklan 1: Saya merasa _referensi aset_ akan ditangani secara elegan oleh proposal di #20 dan dibahas https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071

Iklan 2: Saya tidak akan memperumitnya sama sekali. Satu-satunya hal yang akan saya gunakan untuk transklusi adalah sintaks penurunan harga reguler misalnya [Some Text](path/to/blueprint/file.apib) atau [Some Text](path/to/blueprint/file.apib#resource-name) . Untuk penyertaan, saya akan mengikuti prinsip yang sama seperti untuk aset di drafter, misalnya gunakan : sebelum referensi. Sesuatu seperti https://Gist.github.com/zdne/8804418#aliens -question-aliens_question

Saya pikir ini bisa cukup untuk memulai?

Saya pikir ini bisa cukup untuk memulai?

Sepakat. Saya baru menyadari bahwa Anda membuat perbedaan antara memasukkan "aset" dan menyertakan "sumber daya"/"grup sumber daya". Saya telah memikirkan semuanya sebagai "simpul" untuk dimasukkan sesuka hati.

Untuk poin kedua, saya pikir akan berguna untuk merujuk sintaks MultiMarkdown yang ada untuk transklusi:

This is some text.

{{some_other_file.txt}}

Another paragraph

Ini sepertinya cara sederhana untuk memasukkan sumber daya? (atau memang, teks/simpul arbitrer?)

Jadi untuk memperjelas pendapat saya:

1. Saya pikir sintaks yang baik untuk aset yang direferensikan adalah :[]() atau =[]() seperti yang dibahas
2. Saya pikir sintaks yang baik untuk transklusi adalah {{ }} seperti yang digunakan oleh multimarkdown.

Dan juga untuk memperjelas beberapa kosakata: Saya _berpikir_ bahwa ketika Anda mengatakan "inklusi" Anda mengacu pada apa yang saya maksud ketika saya mengatakan "transklusi", yaitu, sepenuhnya mengganti placeholder dengan teks dari file lain.

Jika saya memahami dengan benar, perbedaan antara "referensi" dan "penyertaan"/"transklusi" hanyalah demi _rendering_, katakanlah ke html atau pdf. Untuk parser, tidak masalah jika aset (misalnya) direferensikan atau ditransklusi, hasil AST yang sama. Apakah itu benar?

1. Saya pikir sintaks yang baik untuk aset yang direferensikan adalah: atau = seperti yang dibahas
2. Saya pikir sintaks yang baik untuk transklusi adalah {{ }} seperti yang digunakan oleh multi penurunan harga.

Mengapa harus memiliki keduanya, bukan hanya satu metode? Apakah ada manfaat untuk membedakan keduanya secara sintaksis? Secara pribadi saya lebih suka nomor satu karena masih dirender sebagai Anda dapat mengikuti dengan penurunan harga biasa?

Saya pikir ketika Anda mengatakan "penyertaan" Anda mengacu pada apa yang saya maksud ketika saya mengatakan "transklusi", yaitu, sepenuhnya mengganti placeholder dengan teks dari file lain.

Setuju, akan mencoba menggunakan transclusion mulai sekarang. Terima kasih!

Jika saya memahami dengan benar, perbedaan antara "referensi" dan "penyertaan"/"transklusi" hanyalah demi rendering

Tidak juga. Menurut pendapat saya, merujuk (membuat referensi) seharusnya hanya menambahkan tautan ke output (AST) dan meninggalkan sisanya pada perkakas (https://github.com/apiaryio/api-blueprint/issues/20#issuecomment-26766374 )

Translcusion harus menginstruksikan parser (atau preprocessor) untuk menarik konten ke dalam...

Hanya pembaruan di sini: Ini memang direncanakan dan sangat dibutuhkan. Kami sedang mengerjakan alat yang memungkinkan hal ini. Sementara itu, jika Anda tidak bergantung pada editor online Apiary, Anda dapat melakukan sesuatu seperti https://Gist.github.com/danvine/11087404 atau pendekatan serupa lainnya (saya tahu setidaknya beberapa alat berbasis tegukan untuk ini).

Whiskey sekarang mendukung ekstensi .apib dan membuat pengeditan file penurunan harga besar menjadi lebih mudah dengan tampilan garis besarnya: http://vimeo.com/album/3108294/video/110486733

http://9muses.se/erato/ dan http://25.io/mou/ juga mendukung .apib jika Anda menginginkan aplikasi desktop (untuk Mac)

Robert CrooksDirektur Layanan Pembelajaran
Brightcove, Inc

Pada 29 Desember 2015, pukul 16:08, Kevin Ingersoll [email protected] menulis:

Wiski sekarang mendukung .apib
ekstensi dan membuat pengeditan file penurunan harga besar menjadi lebih mudah dengan tampilan garis besarnya: http://vimeo.com/album/3108294/video/110486733

—
Balas email ini secara langsung atau lihat di GitHub
.

Hai @bcls dan @holic , terima kasih telah menunjukkan editor ini!

Terkait: https://github.com/apiaryio/api-blueprint/issues/20#issuecomment -77108398

Apakah ada keputusan yang dibuat oleh pengembang inti tentang hal ini? Sudah luar biasa sejak 2013 dan sejauh ini tidak ada jawaban yang jelas, bisakah kita menarik garis untuk ini?

Hei @ foxx belum ada keputusan yang jelas tentang hal ini – saya condong ke sintaks transklusi yang diperkenalkan di Hercule :

FORMAT: 1A

# Gist Fox API
Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).

# Group Gist

:[Gist](blueprint/gist.md)

:[Gists](blueprint/gists.md)

Kecuali

`````` penurunan harga

• Model

+ Body

  ```
  :[](gist.json)
  ```

``````

Karena blok kode harus tetap buram ke parser/preprocessor.

Juga saya tidak berpikir transklusi harus bekerja pada tingkat mana pun - file yang ditransklusikan harus merupakan cetak biru yang valid itu sendiri.

Adapun komitmen untuk ini – ini cukup tinggi pada peta jalan fitur – tetapi belum ada ETA.

Saya akan menghargai setiap komentar atau pemikiran tentang ini dan juga pada fitur visibilitas peta jalan.

Terima kasih!

Sintaks transklusi sepertinya merupakan proposal terbaik sejauh ini, ini adalah pendekatan yang elegan dan bersih, dan lebih baik daripada saran lain yang pernah saya lihat sejauh ini. Fwiw, +1 dari saya.

ada berita tentang ini?

pendekatan dengan transklusi tampaknya baik bagi saya, saya tidak melihat ada kerugian untuk itu.

Untuk saat ini saya sarankan untuk menggunakan Hercule dan sintaks :[Gist](blueprint/gist.md) . Akan bekerja untuk mem-backportnya kembali ke spesifikasi API Blueprint dan rantai alat parser

Apakah ada yang dilakukan untuk masalah ini? Saya juga ingin membagi file apib yang lebih besar menjadi beberapa.
Terima kasih!

Hai @adams-sarah sayangnya bukan dari pihak saya. Saya masih mendukung penggunaan Hercule (https://github.com/jamesramsay/hercule) karena ini bekerja dengan cukup baik – satu-satunya kelemahan adalah Anda tidak akan dapat mengedit banyak file di Apiary.io. Beri tahu saya jika saya dapat membantu entah bagaimana!

+1 untuk penggunaan hercule https://github.com/jamesramsay/hercule
kami telah menggunakannya untuk sementara waktu sekarang dan berharap itu masih akan menemukan jalannya ke dalam spesifikasi apib

:+1: untuk penambahan fitur ini.

Saya juga mendukung metodologi TOC/indeks tunggal. Transklusi agak terlalu fleksibel dan belum diskalakan dalam dokumen besar berbasis wiki dalam pengalaman saya sebelumnya.

Kami pasti harus memasukkan ini ke dalam parser itu sendiri untuk mendukung peta sumber.

Sementara itu, kami telah menyiapkan contoh nyata untuk menunjukkan cara menggunakan Hercule – https://github.com/apiaryio/api.apiblueprint.org

@zdne dalam penggunaan json-schema kami (melalui interagent/prmd) kami membaginya di sepanjang garis sumber daya dan pada dasarnya menegakkan struktur direktori tertentu untuk menyiratkan inklusi (kurang lebih itu membangun skema tingkat atas yang memiliki semua barang di direktori sebagai subskema, sehingga mengubah tingkat hal). Ini jelas sangat khusus untuk apa yang kami lakukan dan tidak terlalu sesuai untuk kasus Anda, tetapi ingin berbagi pengalaman kami. Dibandingkan dengan itu, saya pikir transklusi tampak jauh lebih elegan/fleksibel, tetapi pasti akan menyenangkan juga memiliki beberapa cara langsung untuk memiliki TOC/indeks terkonsolidasi. Mungkin itu mirip dengan apa yang kami lakukan, yaitu Anda membuat cetak biru uber untuk dijadikan sebagai indeks ini dan kemudian mentransklusikan/mereferensikan sub-cetak biru di dalamnya. Saya dapat melihat hal itu terjadi secara otomatis sebagai sesuatu yang baik, tetapi juga sebagai canggung jika itu tidak terjadi untuk melakukan apa yang Anda inginkan. Bagaimanapun, jauh untuk mengatakan saya akan senang untuk mendiskusikan/berbagi pengalaman saya lebih lanjut jika itu akan membantu.

Apa status fitur ini?
Kami menggunakan paket Pro di Apiary.io dan kami membutuhkan fitur ini

@DavidBM Saya memiliki masalah yang sama. bagaimana saya menyiasatinya adalah memiliki dua dokumen apiary.apib .

Belum dikompilasi

apiary-source.apib - sumber yang tidak dikompilasi yang menggunakan Fitur Sertakan

FORMAT: 1A
HOST: https://api.example.com

# Hello World

<!-- include(blueprint/posts.apib) -->

Menyusun

Anda cukup menjalankan:

aglio --input apiary-source.apib --compile --output apiary.apib

apiary.apib Anda sekarang harus menyertakan konten blueprint/posts.apib di dalamnya.

Hai, terima kasih! Ya, tetapi Anda tidak dapat mengedit dokumen di apiary.io

Kami sudah memiliki solusi yang disesuaikan dengan Hercule, tetapi tujuan membayar peternakan lebah pro bagi kami adalah membiarkan manajer produk memperbarui dokumentasi tanpa memasukkan git. Saya khawatir ini benar-benar menghalangi kami dan kami akan membatalkan kontrak dengan Apiary jika ini tidak diselesaikan.

Saya tidak akan mengharapkan ini dalam keadaan ini setelah Hercule dan alat-alat lain untuk begitu banyak waktu yang tersedia.

Ini sangat sangat mengecewakan :(

Halo semuanya, saya minta maaf karena terlambat datang ke sini dan membuka kembali serta menggali hal-hal 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 tidak 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 digunakan kembali menjadi respons yang berbeda dengan mudah. Adakah yang berhasil melakukan ini?

Akan sangat bagus jika masalah ini mendapat perhatian. Kami memiliki 26000 baris dalam Cetak Biru API kami dan membuatnya sangat sulit untuk dikelola

Kami menerapkan pengujian Kontrak menggunakan Dredd dan kami menggunakan Aglio, tetapi akan lebih bagus jika ini ditambahkan sehingga kami tidak perlu melakukannya

Salah satu alasannya adalah kami sering mengulangi desain :) Ketika masalah ini dibuka, tidak ada MSON dan kami masih bingung dengan transklusi vs referensi.

Tapi sebagai catatan, apa kebutuhan Anda di sana? Apakah itu hanya manajemen multifile dan kompilasi satu dokumen sebagai hasilnya atau apakah Anda juga berbicara tentang penggunaan kembali model dan berbagi potongan-potongan di beberapa dokumen deskripsi API?

Salah satu alasannya adalah kami sering mengulangi desain :) Ketika masalah ini dibuka, tidak ada MSON dan kami masih bingung dengan transklusi vs referensi.

Tapi sebagai catatan, apa kebutuhan Anda di sana? Apakah itu hanya manajemen multifile dan kompilasi satu dokumen sebagai hasilnya atau apakah Anda juga berbicara tentang penggunaan kembali model dan berbagi potongan-potongan di beberapa dokumen deskripsi API?

Kami memiliki respons standar yang berasal dari banyak titik akhir kami. kami ingin dapat mendefinisikannya di satu tempat, di dekat perpustakaan yang menampungnya, dan kemudian mengimpornya ke mana pun kami perlu menanggapinya.