Membuat Dokumentasi API Otomatis Pada Laravel Tanpa Anotasi Menggunakan Swagger
Alternatif Laravel untuk mendokumentasikan API Laravel secara otomatis melalui rules request dan daftar route.
Cerita ini berbagi pendekatan untuk secara otomatis menghasilkan dokumentasi untuk Laravel API dan routes tanpa membuat dan memelihara anotasi Swagger.
Swagger adalah alat yang hebat untuk membuat dokumentasi API. Tapi ada beberapa masalah.
Perhatikan juga bahwa ini bukan masalah Swagger secara langsung, karena Swagger bukan hanya alat untuk Laravel, ini adalah alat untuk dokumentasi API lainnya.
Laravel adalah framework yang sangat canggih, tetapi dapat menghasilkan banyak dokumentasi hanya dengan mengikuti pola desain dan mengekstrak informasi.
Masalah menggunakan Swagger
permasalahan ke 1
Tulis dan pertahankan anotasi swagger.
Ini adalah masalah besar. setiap kali Anda mengubah API. Anda harus memperbarui anotasi swagger untuk mencerminkan status terbaru API Anda, seperti menambahkan/menghapus parameter kueri atau mengubah aturan validasi API Anda.
Di bawah ini adalah contoh sederhana dari anotasi Swagger. Untuk API yang memerlukan banyak parameter, memperbarui anotasi dapat menjadi masalah produktivitas yang besar bagi pengembang dan peninjau kode. Dalam beberapa kasus, dokumentasi aplikasi tidak terpelihara karena pengembang lupa memperbarui dokumentasi.
Contoh anotasi Swagger
Permasalahan ke 2
Parameter input sudah ditentukan sebelumnya. Setelah parameter Swagger ditentukan, parameter tersebut tidak dapat diubah dari UI Swagger saat dalam perjalanan. Dalam kasus seperti itu, QA harus menggunakan Postman lagi. Khusus untuk parameter GET, ini diperbaiki dalam bentuk <input>, <select>, dll. dan Anda tidak dapat mengujinya dalam skenario yang berbeda kecuali Anda menambahkannya ke anotasi Anda.
Lagi pula, masalahnya bukan masalah besar. Swagger UI adalah alat yang dominan, dan pendekatan alternatif yang disajikan dalam artikel ini membahas dua masalah ini.
konsep
Kami membutuhkan solusi yang memungkinkan pengembang untuk fokus pada penulisan kode, mengikuti pola desain praktik terbaik, dan tidak menghabiskan waktu untuk menulis/mempertahankan dokumentasi.
kami juga membutuhkan alat dokumentasi yang dapat secara otomatis menghasilkan dokumentasi API dan membaginya antara MS Teams/Slack/Confluence dalam bentuk tabel HTML agar mudah dibaca.
Ada beberapa upaya di masa lalu untuk secara otomatis menghasilkan anotasi Swagger untuk Laravel, seperti laravel-auto-generate-swagger.
Penggunaan
Agar plugin ini berfungsi, Anda harus mengikuti pola desain dengan menginjeksi kelas request di dalam controller Anda.
Sama seperti laravel-auto-generate-swagger, tool yang kami hadirkan mengikuti pola desain yang sama. Ini menyediakan UI baru yang dapat disajikan sebagai situs statis atau langsung dari aplikasi Anda (mendukung middleware) pada routes pilihan Anda.
Ini mengikuti pola desain seperti:
Pola Desain Laravel menyuntikkan Request ke Controller.
Seperti yang Anda lihat, saya menginjeksi kelas request ke controller. Juga, semua aturan validasi didefinisikan dalam kelas request.
Bagaimana cara meng-install
langkah 1
Instal tool. Karena Anda tidak memerlukan tool ini dalam produksi, disarankan untuk hanya menyediakan --dev.
composer require rakutentech/laravel-request-docs --dev
langkah 2
Selanjutnya, kami mempublikasikan file konfigurasi yang memungkinkan kami memperbarui informasi routes yang diperlukan untuk menyediakan Laravel Requests Dashboard.
php artisan vendor:publish --tag=request-docs-config
selesai
Buka /request-docs
Jika Anda ingin mendapatkan HTML statis sehingga Anda dapat mempublikasikannya ke halaman GitHub atau lainnya, ada baris perintah yang disediakan oleh paket untuk menghasilkan HTML mentah untuk dokumentasi Anda sebagai php artisan lrd:generate.
Hasil akhir
fitur 1
Semua routes, Method, controller, middleware, dan informasi atribut request dikumpulkan secara otomatis tanpa menulis anotasi.
Informasi dirender menggunakan tabel HTML, sehingga Anda dapat menyalinnya ke clipboard dan menempelkannya sebagai tabel ke tim Slack/MS/Excel atau Confluence.
Informasi tambahan tentang rules validasi tentang bagaimana atribut divalidasi berguna saat menguji kumpulan API. Ini bukan di Swagger di mana Anda harus menulis deskripsi atribut secara manual. Sekali lagi, ini dimungkinkan berkat struktur Laravel yang elegan dan penamaan yang ramah.
Tangkapan layar dokumentasi otomatis Laravel.
fitur2
Coba API kami.
Dasbor LRD (Laravel request docs) menyediakan antarmuka untuk mengirim request langsung dari browser Anda dengan cara yang sama seperti Swagger. Ini memiliki dukungan middleware dan pembaruan sidebar berdasarkan respons kesalahan/sukses untuk melacak request. sidebar juga membantu Anda melompat di antara permintaan yang berbeda melalui tautan anchor.
Contoh Response
Itu saja untuk alat ini. Kami berharap alat ini membantu Anda secara otomatis menghasilkan dokumentasi untuk aplikasi Laravel Anda.
fitur3
Print kueri SQL request.
Ini juga dapat dilakukan dengan menggunakan bilah debug PHP, tetapi saya juga menambahkan bagian SQL tempat setiap kueri ditampilkan.
Contoh Output SQL
mungkin artikel ini sangat berguna bagi anda seorang backend developer yang sedang diminta dokumentasi oleh QA atau atau rekan kerja anda lainnya yang sedang garap project yang sama :D