Pembangunan Laravel: Bagaimana menggunakan Laravel Swagger untuk menjana dokumentasi API?

Pembangunan Laravel: Bagaimana cara menggunakan Laravel Swagger untuk menjana dokumentasi API?

Bekerja dengan dokumentasi API selalunya merupakan tugas yang membosankan tetapi penting apabila membangunkan aplikasi web. Gunakan Swagger untuk menjana dan menggambarkan dokumentasi API secara automatik. Dalam pembangunan Laravel, kami boleh menggunakan pakej sambungan Laravel Swagger untuk menjana dokumentasi API Swagger dengan mudah. Artikel ini akan membimbing anda tentang cara menggunakan Laravel Swagger dengan Laravel.

1. Pasang Laravel Swagger

Gunakan Komposer untuk memasang pakej sambungan Laravel Swagger:

composer require darkaonline/l5-swagger

2. Konfigurasikan Laravel Swagger

Laravel Swagger bergantung pada Swagger UI, jadi kami perlu menerbitkan sumber Swagger UI ke direktori awam Laravel Gunakan arahan berikut untuk menyelesaikan penerbitan:

php artisan vendor:publish --provider "L5SwaggerL5SwaggerServiceProvider"

Selepas melaksanakan arahan penerbitan, ia akan menjadi. dalam direktori public/vendor Lihat direktori swagger-ui, yang mengandungi semua sumber UI Swagger.

Seterusnya, tambahkan baris berikut pada fail konfigurasi Laravel config/app.php:

'providers' => [
    ...
    L5SwaggerL5SwaggerServiceProvider::class,
],

'aliases' => [
    ...
    'Swagger' => L5SwaggerFacadesL5Swagger::class,
],

3. Tambah anotasi Swagger

untuk memberitahu Laravel bahawa Swagger tidak membuat kesimpulan Format API, kita perlu menambah anotasi Swagger dalam kod. Anotasi ini membolehkan Laravel Swagger menghuraikan API anda secara automatik dan menjana dokumentasi yang sepadan.

/**
 * @OAGet(
 *      path="/users",
 *      operationId="getUsersList",
 *      tags={"Users"},
 *      summary="Get list of registered users",
 *      description="Returns list of users",
 *      @OAResponse(response="200", description="successful operation"),
 *      @OAResponse(response=401, description="Unauthorized"),
 *      @OAResponse(response=403, description="Forbidden"),
 *      @OAResponse(response=404, description="Not Found"),
 *      @OAResponse(response=500, description="Internal Server Error")
 *     )
 */

Dalam contoh di atas, kami menggunakan anotasi @OAGet untuk menunjukkan bahawa ini ialah permintaan GET. path anotasi mentakrifkan laluan ke API. Anotasi tags dan summary digunakan untuk memaparkan petikan dan teg dalam dokumen Swagger. Akhir sekali, anotasi @OAResponse menunjukkan keadaan respons yang mungkin.

4. Lihat dokumentasi Swagger dalam Laravel

Selepas melengkapkan semua langkah sebelumnya, kami boleh menggunakan URL berikut untuk melihat dokumentasi Laravel Swagger:

http://your-app.dev/api/documentation

(Sila ambil perhatian bahawa jika anda menggunakan Laravel 5.4 atau lebih tinggi, anda tidak perlu mentakrifkan .dev, sila gunakan .test atau nama domain tempatan lain sebagai gantinya)

Mulakan pelayan pembangunan Laravel dan akses URL di atas dan anda sepatutnya dapat melihat dokumentasi Swagger yang dijana secara automatik dalam penyemak imbas anda.

Dalam dokumentasi Swagger, anda boleh melihat API yang ditentukan, menguji API terhadap anotasi Swagger yang ditambahkan pada API dan melihat keadaan respons yang mungkin.

Ringkasan

Dalam artikel ini, kami mempelajari cara menjana dokumentasi API Swagger dengan mudah menggunakan pakej sambungan Laravel Swagger. Mula-mula, kami memasang Laravel Swagger, kemudian memulakan Swagger dan menambahkan anotasi Swagger pada API. Akhirnya, kami melihat dokumentasi yang dihasilkan oleh Laravel Swagger.

Menggunakan Laravel Swagger boleh mengurangkan beban menulis dokumentasi API secara manual dan mengelakkan kemungkinan ralat dan ketidakkonsistenan. Dengan menggunakan UI Swagger, kami boleh melihat dan menguji API dengan lebih mudah, sambil menyediakan antara muka mesra pembangun.

Atas ialah kandungan terperinci Pembangunan Laravel: Bagaimana menggunakan Laravel Swagger untuk menjana dokumentasi API?. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!