Cara menulis dokumentasi API berdasarkan API RESTful menggunakan spesifikasi Swagger dalam PHP

Dalam aplikasi web moden, RESTful API ialah bahagian penting dalam aplikasi Internet. RESTful API ialah gaya seni bina berdasarkan protokol HTTP, yang membolehkan pelanggan mengakses sumber pada pelayan melalui permintaan HTTP. Untuk menjadikan aplikasi lebih mudah digunakan, dokumentasi API perlu ditulis. Artikel ini akan memperkenalkan cara menggunakan spesifikasi Swagger untuk menulis dokumentasi API berdasarkan API RESTful.

Swagger ialah spesifikasi API popular yang membenarkan pembangun menulis dokumentasi yang boleh dibaca mesin untuk API. Spesifikasi Swagger mentakrifkan pelbagai aspek API, termasuk titik akhir, parameter, badan permintaan dan respons. Ia juga membolehkan pembangun mentakrifkan pelbagai aspek API seperti keselamatan, pengesahan dan versi. Swagger membolehkan pembangun menjana kod sisi klien dan pelayan secara automatik daripada hampir mana-mana timbunan teknologi.

Berikut ialah beberapa faedah menulis dokumentasi API menggunakan Swagger:

1. Mudah dibaca dan difahami: Swagger menyediakan format dokumentasi API yang mudah dibaca dan difahami, jadi pembangun dan Pengguna API boleh memahami pelbagai aspek API dengan lebih mudah.
2. Menjana dokumentasi secara automatik: Swagger boleh menjana dokumentasi API, yang membantu mengurangkan masa menulis dokumentasi.
3. Penjanaan kod automatik: Swagger boleh menjana kod klien dan pelayan secara automatik dalam pelbagai bahasa menggunakan spesifikasi API, yang akan mempercepatkan pembangunan dan ujian API.

Berikut ialah langkah cara menulis dokumentasi API menggunakan Swagger dalam PHP:

1. Tambah Swagger pada projek PHP anda

Pertama, Anda perlu memasang Swagger ke dalam projek PHP anda. Swagger boleh dipasang menggunakan Komposer.

komposer memerlukan zirkot/swagger-php

2. Tentukan spesifikasi API

Setelah Swagger telah ditambahkan pada projek anda, langkah seterusnya adalah untuk menentukan Spesifikasi API. Anda boleh menentukan spesifikasi Swagger dalam kod PHP menggunakan sintaks anotasi. Berikut ialah contoh:

/**

• @OAGet(
• path="/articles",
• summary="Dapatkan senarai artikel",
• @OAResponse(response ="200", description="Senarai artikel")
• )
  */

Dalam contoh ini, kami mentakrifkan permintaan GET bernama "/articles" yang mengembalikan artikel kumpulan. Dalam anotasi @OAGet, kami menentukan titik akhir dan ringkasan. Dalam anotasi @OAResponse, kami mentakrifkan 200 respons dan rentetan yang menerangkan respons.

Anda boleh menentukan pelbagai aspek spesifikasi API melalui:

1. @OAGet: Mentakrifkan titik akhir untuk jenis permintaan HTTP GET.
2. laluan: Tentukan laluan titik terminal.
3. ringkasan: Menyediakan pengenalan ringkas kepada titik terminal.
4. @OAResponse: Tentukan respons.
5. balas: Nyatakan kod respons.
6. penerangan: Menyediakan penerangan tentang respons.
7. Jana Dokumentasi API

Setelah anda menentukan spesifikasi API, langkah seterusnya ialah menukarnya menjadi dokumen berformat. Anda boleh menggunakan UI Swagger untuk memaparkan dokumentasi API. Swagger UI ialah alat dengan dokumentasi API interaktif yang membolehkan pengguna menguji titik akhir API dan melihat spesifikasi API.

Untuk menjana dokumentasi UI Swagger, anda perlu menggunakan fail statik Swagger yang disediakan oleh pakej Swagger-php. Fail UI Swagger boleh disalin ke dalam projek anda menggunakan arahan berikut:

vendor/bin/openapi --output public/swagger.json app/Http/Controllers

Dalam arahan ini, Kami menyimpan fail swagger.json dalam folder akar aplikasi dalam folder awam. Bergantung pada keperluan projek anda, anda boleh menjana fail statik anda sendiri.

4. Akses dokumentasi API

Selepas menjana dokumentasi Swagger UI, anda boleh mengaksesnya melalui penyemak imbas. Apabila mengakses UI Swagger, anda perlu menyediakan laluan ke fail JSON Swagger. Berikut ialah contoh URL:

http://localhost/swaggers/public/index.html?url=http://localhost/swaggers/public/swagger.json

Dalam URL ini , kami menentukan laluan ke fail JSON Swagger.

Kesimpulan

Artikel ini memperkenalkan cara menggunakan spesifikasi Swagger untuk menulis dokumentasi API berdasarkan API RESTful. Kami membincangkan faedah Swagger dan langkah-langkah untuk menggunakan Swagger untuk menulis spesifikasi API dan menjana dokumentasi API dalam projek PHP. Dengan mengikuti langkah-langkah ini, anda boleh menulis dokumentasi API yang mudah dibaca dan difahami dengan lebih mudah, mempercepatkan pembangunan dan ujian API.

Atas ialah kandungan terperinci Cara menulis dokumentasi API berdasarkan API RESTful menggunakan spesifikasi Swagger dalam PHP. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!