在开发API时，编写和维护API文档往往是一个繁琐且容易出错的过程。手动编写文档不仅耗时，还容易因为代码更新而导致文档过时。为了解决这个问题，可以使用 zircote/swagger-php 这个工具来自动生成交互式API文档。swagger-php 是一个基于PHP的库，它通过解析代码中的注释来生成符合OpenAPI规范的API文档。
zircote/swagger-php首先，你需要通过Composer来安装 zircote/swagger-php：
composer require zircote/swagger-php
swagger-php 通过解析代码中的注释来生成API文档。你可以在控制器、模型或其他相关类和方法上添加注释来描述API的各个部分。
以下是一个简单的示例：
/**
* @OA\Info(
* title="My First API",
* version="1.0.0",
* description="This is a sample API for demonstration purposes."
* )
*/
/**
* @OA\Get(
* path="/api/users",
* summary="Get a list of users",
* @OA\Response(
* response=200,
* description="A list of users",
* @OA\JsonContent(
* type="array",
* @OA\Items(ref="#/components/schemas/User")
* )
* )
* )
*/
public function getUsers()
{
// 你的业务逻辑
}
/**
* @OA\Schema(
* schema="User",
* type="object",
* @OA\Property(
* property="id",
* type="integer"
* ),
* @OA\Property(
* property="name",
* type="string"
* )
* )
*/
class User
{
public $id;
public $name;
}
在代码中添加完注释后，你可以使用 swagger-php 提供的命令行工具来生成API文档。
./vendor/bin/openapi --output ./public/swagger.json ./app
这个命令会扫描 ./app 目录下的所有PHP文件，并生成一个 swagger.json 文件到 ./public 目录下。
生成的 swagger.json 文件可以被Swagger UI加载，从而提供一个交互式的API文档界面。你可以将 swagger.json 文件放在你的Web服务器上，并通过Swagger UI来展示它。
你可以使用官方的Swagger UI，或者将其集成到你的项目中。以下是一个简单的HTML文件示例，用于加载Swagger UI：
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>API Documentation</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@3/swagger-ui.css">
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>
const ui = SwaggerUIBundle({
url: "/swagger.json",
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
layout: "StandaloneLayout"
});
</script>
</body>
</html>
为了确保文档始终与代码同步，你可以将文档生成步骤集成到你的CI/CD流程中。例如，在每次代码提交或部署时自动生成并更新API文档。
通过使用 zircote/swagger-php，你可以告别手动编写API文档的噩梦。只需在代码中添加注释，swagger-php 就能自动生成符合OpenAPI规范的API文档，并通过Swagger UI提供一个交互式的文档界面。这不仅节省了时间，还确保了文档的准确性和实时性。