Fosrestbundle: Pembuatan dokumentasi REST API di luar rute

Periksa http://getfrapi.com/ screencast untuk beberapa inspirasi.

Aku sudah melihatnya. Tapi saya tidak suka banyak hal dalam realisasinya. Pertama-tama, REST mereka tidak RESTful :-D

"inspirasi" dan saya tidak berbicara tentang istirahat mereka tetapi generasi doc (dan tes) mereka :)

Saya pribadi tidak menyukainya, tetapi bisakah kita mendiskusikan pembuatan dokumentasi dalam format WADL?

http://www.w3.org/Submission/wadl/

Saya ingin tahu apakah arah yang lebih baik daripada generasi adalah menyediakan beberapa pembantu tampilan yang memungkinkan untuk membangun pengontrol/tampilan dokumentasi dengan cepat. Ini tampaknya lebih baik daripada sekadar menghasilkan struktur dan akan lebih dapat diperluas/dipelihara. Dengan kata lain saya pikir menghasilkan dokumen API berfungsi dengan baik untuk kasus penggunaan FRAPI (masuk ke aplikasi) tetapi mempertanyakan apakah kita memerlukan fitur ini "apa adanya" atau apakah itu masuk akal.

Apakah kita berbicara tentang dokumentasi untuk klien?

Ingatlah, itulah yang REST coba hindari :)

odino: tentu. tetapi ada hal-hal seperti fakta bahwa meskipun Anda mengikuti HATEAOS, Anda perlu memeriksa header. juga sementara Anda harus tahu untuk mengharapkan kode status yang berbeda, masih bagus untuk mengetahui kode status apa yang "lebih mungkin". itu hanya bagus untuk tinjauan santai API.

juga topik lain yang harus diabaikan: beberapa klien suka membunuh pohon dan senang tidak perlu membuang banyak waktu untuk mengisi halaman kertas ini :)

setuju, satu-satunya hal yang harus kita hindari adalah sangat bergantung pada dokumentasi yang dihasilkan, jika tidak, kita akan meniru WSDL

jempol ke bawah untuk pembunuh pohon :)

Sejauh yang saya tahu, dokumen REST API yang sebenarnya adalah tentang mendefinisikan jenis media dan hubungannya, bukan URL. Misal http://kenai.com/projects/suncloudapis/pages/Home , http://amundsen.com/media-types/collection/

Tetapi untuk API HTTP sederhana, yang akan terjadi pada 80% proyek web, fitur ini akan tetap berguna.

Ya vladar, template URI jelas jahat. Tetapi jika kita perlu mengembangkan bundel REST, kita harus mengikuti prinsip-prinsip itu.

Template URI akan cocok untuk ApiBundle

Mungkin bisa mengambil konsep dari http://swagger.wordnik.com/

:+1: untuk menyombongkan diri. Ini terlihat luar biasa!

Untuk menciptakan pengalaman serupa, kami mungkin dapat:

• Metode parsing ditandai sebagai @apidoc atau sesuatu
• Dapatkan deskripsi metode dan parameter dari docblock pada metode yang ditandai @apidoc
• Izinkan pengujian panggilan sebaris berdasarkan per tindakan.

Secara keseluruhan, saya pikir mencapai layar seperti Swagger cukup bisa dilakukan dan masuk akal untuk Bundle ini.

Pilihan lain adalah hanya menghasilkan JSON yang dikonsumsi Swagger tetapi itu datang dengan beberapa bobot (Java) ... Lebih suka melihat implementasi "suka".

Menghasilkan JSON yang kompatibel adalah pemikiran pertama saya. Saya akan menggali sedikit lebih dalam di akhir pekan, mungkin ada beberapa prototipe cepat yang mungkin.

@pminnieur sepertinya kita bisa dengan mudah menyediakan fungsionalitas dasar yang sama daripada mengintegrasikan.

Setidaknya itu bisa berfungsi seperti https://github.com/FriendsOfSymfony/FOSJsRoutingBundle - cukup tambahkan beberapa HTML/CSS mewah dan ekspos rute RESTful Anda dengan semacam dokumen API. Mungkin kita bisa menggunakan beberapa Anotasi untuk mendukung informasi lebih lanjut.

Saya ingin memulai dengan ini tetapi saya pikir akan lebih baik untuk memasukkan kode ke dalam bundel khusus (misalnya FOSRestAPIExplorerBundle). Pertanyaannya adalah, apakah kami hanya mendukung API Swagger (jadi Swagger digunakan untuk memvisualisasikan informasi yang dikumpulkan dan diekspos di JSON) atau haruskah kami menyediakan antarmuka web kami sendiri juga?

Bundel terpisah terdengar seperti ide yang bagus. jika kami hanya mendukung kesombongan, kami mungkin ingin mengatakannya dalam nama Bundel. saya tidak tahu apakah kami juga ingin mendukung sesuatu yang lain. tergantung pada motivasi Anda dan kualitas kesombongan. satu pertanyaan tentang kesombongan: bagaimana cara kerjanya dengan API internal yang tidak ingin diekspos ke layanan eksternal?

Saya pikir Anda tidak perlu membuat URL yang mengembalikan Swagger JSON menjadi publik jika Anda tidak ingin menjadi publik ... :D Serius, saya ingin menggunakan anotasi dan jika Anda tidak ingin rute menjadi publik, Anda tidak akan menambahkan anotasi @Expose() atau menambahkan @Expose(false) -- sesuatu seperti ini. Sama seperti FOSJsRoutingBundle yang dapat dikonfigurasi bagaimana menghadapinya (mengekspos semuanya secara default, atau mengekspos daftar putih). Jika maksud Anda "inilah tautan untuk API publik kami dan tautan ini hanya untuk Anda", kami dapat menambahkan anotasi seperti @Api("public") dan @Api("private") termasuk komponen keamanan sehingga Anda dapat membagikan API yang berbeda dokumentasi ke orang yang berbeda (dan mengontrol akses ke mereka).

Untuk nama: Saya ingin memiliki nama generik, Swagger akan menjadi layanan dokumentasi API pertama yang didukung. Jika orang ingin menambahkan layanan lain, mereka bisa melakukannya (dan tidak boleh memulai dari awal). @odino misalnya bisa menambahkan dukungan WADL. Setidaknya saya ingin menyediakan antarmuka web juga.

Saya membuat repositori GitHub sejauh ini untuk mengumpulkan ide dan masalah sebelum kita mulai. Jangan ragu untuk membuka masalah untuk pertanyaan atau topik apa pun untuk didiskusikan (nama dapat didiskusikan juga, pasti) ;-)

https://github.com/pminnieur/FOSRestApiExplorerBundle

oke bagus. setelah semuanya terbentuk .. kita bisa memindahkannya ke FOS

Apakah Anda berencana memanfaatkan https://github.com/wordnik/swagger-ui sebagai "penampil"?

di tempat pertama, ya. hanya menghasilkan json konform swagger-spec untuk digunakan oleh swagger-ui.

menutup mendukung https://github.com/nelmio/NelmioApiDocBundle

Saya tahu ini sudah sangat tua, tetapi beberapa hal berubah sejak itu dan saya menemukan ini relatif cepat ketika mencari paket/bundel untuk Swagger/Openapi.
Adakah kesempatan untuk mempertimbangkan kembali ini? Karena NelmioApiDocBundle ditinggalkan dan saya tidak dapat melihat alternatif nyata apa pun yang terintegrasi ke dalam Symfony untuk Swagger / OpenApi (atau yang lainnya, RAML, ...?).