swagger-php

swagger-php 是一个基于 PHP 的 OpenAPI 规范（OAS）生成工具，它可以通过 PHPDoc 注解来自动生成 API 文档，支持 OpenAPI 3.0 和 2.0 规范。

适用于 Laravel、Slim、CodeIgniter 等框架。

核心功能

• 自动生成 API 文档：通过 PHP 代码中的注解（annotations），解析代码并生成 swagger.json 或 swagger.yaml。
• 支持 OpenAPI 3.0 和 2.0：可以用于 RESTful API 的标准化文档管理。
• 与 Swagger UI 兼容：生成的 swagger.json 可用于 Swagger UI 进行可视化展示和 API 调试。

安装使用

使用 Composer 安装：

composer require zircote/swagger-php

使用命令行工具生成 API 文档：

php vendor/bin/openapi –output docs/swagger.json .

基本用法

1 添加 swagger-php 注解

在你的 PHP 代码中，你可以使用 PHPDoc 注解来标记 API，如下所示：

<?php

use OpenApi\Annotations as OA;

/**
* @OA\Info(
* title=”示例 API”,
* version=”1.0.0″,
* description=”这是一个使用 swagger-php 生成的 API 文档示例”
* )
*/

/**
* @OA\Get(
* path=”/users”,
* summary=”获取用户列表”,
* tags={“用户”},
* @OA\Response(
* response=200,
* description=”成功返回用户列表”,
* @OA\JsonContent(
* type=”array”,
* @OA\Items(
* type=”object”,
* @OA\Property(property=”id”, type=”integer”, example=1),
* @OA\Property(property=”name”, type=”string”, example=”张三”)
* )
* )
* )
* )
*/
function getUsers() {
echo json_encode([
[“id” => 1, “name” => “张三”],
[“id” => 2, “name” => “李四”]
]);
}

2 生成 API 文档

运行以下命令，扫描指定目录并生成 swagger.json：

php vendor/bin/openapi –output docs/swagger.json .

3 使用 Swagger UI 展示 API

3.1) 下载 Swagger UI

3.2) 在 index.html 中修改

<script>
window.onload = function() {
const ui = SwaggerUIBundle({
url: “docs/swagger.json”,
dom_id: “#swagger-ui”
});
};
</script>

3.3) 运行 php -S localhost:8000 访问 Swagger UI 页面。

常见注解

https://www.49855.net/openapi规范-swagger-规范