Dengan perkembangan pesat Internet, API (Antara Muka Pengaturcaraan Aplikasi) telah menjadi cara standard pembangunan aplikasi moden. API merujuk kepada satu set antara muka yang membolehkan aplikasi bertukar data dan fungsi, membolehkan aplikasi berinteraksi antara satu sama lain dengan mudah dan cepat.
Selepas kami mencipta API, untuk memudahkan pembangun lain menggunakan API kami, kami perlu menulis dokumentasi terperinci untuk API. Walau bagaimanapun, menulis dokumentasi API secara manual adalah tugas yang memakan masa dan memakan tenaga, jadi menggunakan alat automatik untuk penjanaan dokumentasi API adalah sangat perlu dan berkesan.
Artikel ini akan memperkenalkan cara menggunakan PHP dan Swagger untuk menjana dokumen API.
1. Apa itu Swagger?
Swagger ialah spesifikasi untuk menerangkan dan mentakrifkan API RESTful. Ia boleh digunakan untuk menjana dokumentasi yang boleh dibaca manusia, serta penjana kod untuk menjana kod sisi klien dan pelayan. Swagger juga boleh digunakan untuk ujian API dan penyahpepijatan.
2. Pemasangan dan konfigurasi Swagger
Untuk menggunakan Swagger untuk menjana dokumen API, anda perlu memasangnya terlebih dahulu. Kami boleh menggunakan Composer untuk memasang Swagger ialah pengurus pergantungan untuk PHP dan boleh memuat turun versi terkini Swagger.
Gunakan arahan berikut untuk memasang Swagger:
composer require "swagger-api/swagger-ui:^3.50"
Salin selepas log masuk
Selepas pemasangan selesai, kita perlu melakukan beberapa konfigurasi untuk Swagger. Cipta fail swagger.php dalam direktori akar projek dan tambah kod berikut:
<?php
require_once(__DIR__ . '/vendor/autoload.php');
use OpenApiAnnotations as OA;
$swagger = OpenApiscan('/path/to/your/controllers');
header('Content-Type: application/json');
echo $swagger;Salin selepas log masuk
Dalam kod di atas, /path/to/your/controllers hendaklah digantikan dengan laluan pengawal anda sendiri. Selain itu, kami juga perlu menambah beberapa konfigurasi pada fail composer.json:
"config": {
"platform": {
"php": "7.4"
}
},
"autoload": {
"classmap": [
"app/",
"database/",
"routes/",
"tests/"
]
},
"require": {
"php": "^7.4",
"laravel/framework": "^8.40",
"tymon/jwt-auth": "^1.0",
"doctrine/dbal": "^2.13",
"swagger-api/swagger-ui": "^3.50"
},
"require-dev": {
"facade/ignition": "^2.5",
"fzaninotto/faker": "^1.9.1",
"mockery/mockery": "^1.4.2",
"nunomaduro/collision": "^6.0",
"phpunit/phpunit": "^9.3.3"
},Salin selepas log masuk
3 Gunakan Swagger untuk menjana dokumen API
Selepas memasang dan mengkonfigurasi Swagger, kami boleh mula menggunakannya untuk. menjana dokumentasi API. Kita boleh menggunakan arahan berikut untuk menjana dokumentasi API:
php swagger.php > swagger.json
Salin selepas log masuk
Dalam arahan di atas, swagger.php ialah fail konfigurasi Swagger yang baru dibuat dan swagger.json ialah fail dokumentasi API yang kami hasilkan.
4. Gunakan Swagger UI untuk memaparkan dokumen API
Selepas menjana dokumen API, kami berharap dapat memaparkannya supaya orang lain dapat melihatnya. Anda boleh menggunakan UI Swagger untuk memaparkan dokumentasi API. UI Swagger ialah perpustakaan JavaScript yang digunakan untuk memaparkan maklumat API RESTful dan pelaksanaannya diterangkan oleh Swagger.
Kami boleh menambah kandungan berikut pada fail index.php dalam direktori awam:
require_once(__DIR__ . '/../vendor/autoload.php');
$swagger = file_get_contents(__DIR__ . '/../swagger.json');
$swaggerData = json_decode($swagger, true);
?>
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.min.css" >
<style>
html
{
box-sizing: border-box;
overflow: -moz-scrollbars-vertical;
overflow-y: scroll;
}
*, *:before, *:after
{
box-sizing: inherit;
}
body
{
margin:0;
background: #fafafa;
}
</style>
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"> </script>
<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-standalone-preset.js"> </script>
<script>
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
url: "<?php echo '/swagger.json'; ?>",
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
// End Swagger UI call region
window.ui = ui
}
</script>
</body>
</html>Salin selepas log masuk
Dalam kod di atas, kami menggunakan perpustakaan JavaScript UI Swagger, yang melaluinya The API dihasilkan dokumentasi dibentangkan dalam bentuk halaman HTML yang cantik.
Sampel halaman yang menunjukkan dokumentasi API ditunjukkan di bawah:
5 Kesimpulan
Menggunakan Swagger boleh mendokumenkan API Menjana dan mengurus dengan mudah. Artikel ini memperkenalkan cara menggunakan PHP dan Swagger untuk menjana dokumen API. Langkah-langkahnya termasuk memasang dan mengkonfigurasi Swagger, menggunakan Swagger untuk menjana dokumen API dan menggunakan UI Swagger untuk memaparkan dokumen API. Saya percaya bahawa pembaca boleh menggunakan Swagger dengan mudah untuk menjana dokumen API mereka sendiri selepas pengenalan dalam artikel ini.
Atas ialah kandungan terperinci Cara menggunakan PHP dan Swagger untuk penjanaan dokumentasi API. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!
![[Web front-end] Permulaan pantas Node.js](https://img.php.cn/upload/course/000/000/067/662b5d34ba7c0227.png)
