Apicurio-studio: Mendukung referensi ke objek komponen di seluruh dokumen spesifikasi

Gunakan Kasus

Kasus penggunaan utama yang akan dipecahkan ini adalah memberi pengguna kemampuan untuk memusatkan definisi tipe data mereka, mungkin dalam satu file (atau satu set file). Tipe data ini kemudian dapat dimanfaatkan dalam beberapa definisi API dengan merujuk lokasi pusatnya.

Pertimbangan

Untuk mendukung referensi eksternal, diperlukan sejumlah penyempurnaan. Berikut adalah daftar tanpa urutan tertentu:

• Pustaka model data (saat ini oai-ts-core tetapi akan segera apicurio-data-models ) harus ditingkatkan untuk mendukung resolver referensi yang dapat dipasang. Saat ini perpustakaan ini hanya dapat menyelesaikan referensi internal. Sebagai gantinya, konsumen perpustakaan harus dapat menyediakan penyelesai referensi khusus sehingga referensi eksternal dapat berhasil diselesaikan.

• Apicurio Studio harus mendukung sumber daya gaya "hanya tipe data", dengan editor yang berfokus pada perancangan tipe data. Ini memungkinkan alur kerja yang lebih spesifik untuk membuat/mengelola tipe data secara independen dari desain API.

• Saat menyetel jenis di editor Desain API, alat tersebut memerlukan cara untuk memilih jenis dari sumber daya eksternal. Kita perlu mempertimbangkan cara terbaik untuk menampilkan tipe eksternal ini kepada pengguna untuk dipilih. Mungkin kita memerlukan cara bagi Desain API untuk "mengimpor" sumber daya/file lain sehingga UI dapat mempersempit pilihan bagi pengguna dan menampilkannya dengan bijaksana. Ingatlah bahwa editor perlu mengambil dan mengurai sumber daya eksternal apa pun untuk menampilkan tipe data yang tersedia dalam semacam kontrol UI pemilihan.

• Kita mungkin perlu memutuskan apakah sumber daya tipe data yang sedang berlangsung dapat digunakan sebagai sumber untuk referensi eksternal dalam desain API. Dengan kata lain, apakah mungkin untuk mereferensikan tipe data "snapshot" dalam desain API? Atau haruskah kita memerlukan sumber daya Tipe Data menjadi "final" sebelum dapat digunakan sebagai sumber referensi eksternal. Jika yang pertama, maka kami tidak dapat "menyelesaikan" desain API hingga dependensinya juga diselesaikan. Catatan: seluruh konsep ini mengharuskan kita untuk mengimplementasikan sumber daya finalisasi di Apicurio!

• Kita perlu memutuskan seperti apa format $ref saat mereferensikan sumber daya Apicurio. Saat ini setiap Desain API (atau sumber daya Tipe Data teoretis) memiliki ID unik, tetapi ID buram yang dihasilkan saat dibuat. ID tersebut saat ini merupakan satu-satunya cara unik untuk mengidentifikasi sumber daya untuk tujuan resolusi. Setelah sumber daya diselesaikan (jika kami mendukung konsep seperti itu) maka kami mungkin dapat memberikan sumber daya pengenal yang lebih ramah manusia dan kemudian menggunakannya di $ref URI. Apa pun yang kita lakukan, perlu diperhatikan bahwa saat memublikasikan sumber daya ke registri API (fitur lain yang akan datang) $referensi apa pun dalam Desain API perlu diselesaikan oleh registri API dengan cara yang masuk akal.

Berikut adalah beberapa informasi tentang nilai yang diizinkan untuk $ref :

Meskipun nilai $ref adalah URI, itu bukan pencari jaringan, hanya pengenal. Ini berarti bahwa skema tidak perlu dapat diakses di URI itu, tetapi mungkin saja. Pada dasarnya tergantung pada implementasi validator bagaimana URI skema eksternal akan ditangani, tetapi orang tidak boleh berasumsi validator akan mengambil sumber daya jaringan yang ditunjukkan dalam nilai $ref.

Informasi lebih lanjut tentang referensi dapat ditemukan di spesifikasi OpenAPI dan Referensi JSON RFC .

Apakah mungkin untuk memprioritaskan implementasi referensi ke Tipe Data dari spesifikasi lain dalam Apicurio (daripada referensi eksternal pada awalnya)?

Alasan saya mengatakan ini adalah bahwa beberapa fungsi referensi silang diperlukan untuk penggunaan Swagger yang tidak sepele. Misalnya, kami menerapkan berbagai layanan yang berbagi tipe data (misalnya alamat, orang, dll.) dan ingin menggunakan Apicurio untuk spesifikasi semua ini. Namun, saat ini kami tidak bisa karena ketidakmampuan menggunakan referensi silang.

Apakah mungkin untuk memprioritaskan implementasi referensi ke Tipe Data dari spesifikasi lain dalam Apicurio (daripada referensi eksternal pada awalnya)?

Alasan saya mengatakan ini adalah bahwa beberapa fungsi referensi silang diperlukan untuk penggunaan Swagger yang tidak sepele. Misalnya, kami menerapkan berbagai layanan yang berbagi tipe data (misalnya alamat, orang, dll.) dan ingin menggunakan Apicurio untuk spesifikasi semua ini. Namun, saat ini kami tidak bisa karena ketidakmampuan menggunakan referensi silang.

Setuju, ini akan membawa kita ke wilayah aplikasi pembunuh.

@jsenko Sepertinya setelah kami menyelesaikan impl registri, kami memiliki prioritas yang jelas dari komunitas. :)

saya ingin melihat ini, menggunakan apicurio di tempat kerja dan referensi akan sangat berguna untuk tim yang berbeda.

Saya menyadari ini telah memakan waktu cukup lama, tetapi referensi eksternal akan didukung secara resmi pada Beta 2.46, yang merupakan rilis berikutnya (semoga akan selesai besok). Ada UI baru untuk mengimpor Tipe Data dan Respons dari dokumen Apicurio Studio lainnya ke dokumen saat ini. Selain itu, validasi telah diperbarui untuk mendukung penyelesaian http/s eksternal serta referensi internal Apicurio. Ini harus menjadi langkah pertama yang baik menuju dukungan yang matang untuk referensi di seluruh dokumen.