隨著網路的快速發展，API（Application Programming Interface）已成為現代應用程式開發的標準方式。 API是指允許應用程式之間交換資料和功能的一組接口，使得應用程式之間可以方便、快速地互動。
當我們建立了一個API後，為了方便其他開發者使用我們的API，需要為API撰寫詳細的文件。然而，手動編寫API文件是一項耗費時間和精力的工作，因此使用自動化工具進行API文件產生是非常必要且有效的。
本文將介紹如何使用PHP和Swagger進行API文件產生。
一、Swagger是什麼？
Swagger是一種用來描述和定義RESTful APIs的規格。它可以被用於產生人類可讀的文檔，以及程式碼產生器，以產生客戶端和服務端程式碼。 Swagger還可以用於API測試和偵錯。
二、Swagger的安裝與配置
要使用Swagger產生API文檔，首先需要安裝它。我們可以使用Composer來安裝Swagger，Composer是PHP的一個依賴管理器，可以下載最新版本的Swagger。
使用以下指令進行Swagger的安裝：
composer require "swagger-api/swagger-ui:^3.50"
登入後複製
安裝完成後，我們需要為Swagger進行一些設定。在專案根目錄下建立一個swagger.php文件，並加入以下程式碼：
<?php
require_once(__DIR__ . '/vendor/autoload.php');
use OpenApiAnnotations as OA;
$swagger = OpenApiscan('/path/to/your/controllers');
header('Content-Type: application/json');
echo $swagger;登入後複製
在上述程式碼中，/path/to/your/controllers應被替換為你自己的控制器路徑。此外，我們還需要在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"
},登入後複製
三、使用Swagger產生API文件
安裝並設定完Swagger後，我們就可以開始使用它來生成API文件了。我們可以使用以下指令來產生API文件：
php swagger.php > swagger.json
登入後複製
在以上指令中，swagger.php是剛才所建立的Swagger設定文件，swagger.json是我們產生的API文件檔。
四、使用Swagger UI展現API文件
產生API文件後，我們希望將其展現出來，以方便其他人查看。可以使用Swagger UI來展現API文件。 Swagger UI是用來展示Swagger所描述的RESTful API資訊及其實作的JavaScript庫。
我們可以將以下內容加入到public目錄下的index.php檔案中：
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>登入後複製
在上述程式碼中，我們使用了Swagger UI的JavaScript庫，透過該程式庫可以將生成的API文件以美觀的HTML頁面形式展現出來。
展示API文檔的範例頁如下圖所示：
#五、結論
使用Swagger可以方便地對API進行文檔生成和管理。本文介紹了使用PHP和Swagger進行API文件產生的方法，步驟包括安裝和設定Swagger、使用Swagger產生API文件以及使用Swagger UI展現API文件。相信讀者經過本文的介紹後，能夠輕鬆地使用Swagger產生自己的API文件。
以上是如何使用PHP和Swagger進行API文件生成的詳細內容。更多資訊請關注PHP中文網其他相關文章！
