Swagger-PHP 用于 PHP：完整指南及示例

什么是 Swagger-PHP 以及为什么需要它？

Swagger-PHP 是一个强大的 PHP 库，用于以 OpenAPI 格式（以前称为 Swagger）自动生成 REST API 文档。您无需手动编写 YAML 或 JSON 格式的文档，而是通过 PHPDoc 注解直接在代码中描述 API。该库会分析这些注解并生成完整的 OpenAPI 规范，您可以使用 Swagger UI、ReDoc 或其他工具将其可视化。

为什么需要它？

\n
• 自动化：文档始终与代码同步。更改了端点 — 更新注解，文档即可就绪。
\n
• 标准化：OpenAPI 是描述 REST API 的行业标准，受到数百种工具的支持。
\n
• 前端便利性：客户端应用程序的开发人员可以将规范导入 Postman、Insomnia 或生成客户端代码。
\n
• 测试：该规范可用于自动测试 API。
\n
• 交互式文档：Swagger UI 允许您直接在浏览器中测试端点。
\n

安装 Swagger-PHP

通过 Composer（PHP 的标准包管理器）进行安装。在项目根目录下打开终端并执行：

composer require zircote/swagger-php

如果您使用 Laravel、Symfony 或其他框架，安装过程没有区别。安装后，您的项目中会出现 vendor/zircote/swagger-php 文件夹。

附加（可选）：要可视化文档，您需要 Swagger UI。您可以通过 npm 安装它：

npm install swagger-ui-dist

或者直接从 Swagger 官方网站下载预构建版本。

快速入门及代码示例

让我们创建一个简单的任务列表管理 API（Todo List）并为其生成文档。

步骤 1：创建包含您的 API 的文件 index.php：

<?php\n/**\n * @OA\\Info(\n *     title="Todo API",\n *     version="1.0.0",\n *     description="一个用于管理任务的简单 API"\n * )\n * @OA\\Server(\n *     url="http://localhost:8000",\n *     description="本地服务器"\n * )\n */\n\nuse OpenApi\\Annotations as OA;\n\n/**\n * @OA\\Get(\n *     path="/tasks",\n *     summary="获取所有任务的列表",\n *     @OA\\Response(\n *         response=200,\n *         description="成功响应",\n *         @OA\\JsonContent(\n *             type="array",\n *             @OA\\Items(ref="#/components/schemas/Task")\n *         )\n *     )\n * )\n */\nfunction getTasks() {\n    $tasks = [\n        ['id' => 1, 'title' => '买牛奶', 'completed' => false],\n        ['id' => 2, 'title' => '写文章', 'completed' => true]\n    ];\n    header('Content-Type: application/json');\n    echo json_encode($tasks);\n}\n\n/**\n * @OA\\Post(\n *     path="/tasks",\n *     summary="创建新任务",\n *     @OA\\RequestBody(\n *         required=true,\n *         @OA\\JsonContent(ref="#/components/schemas/TaskInput")\n *     ),\n *     @OA\\Response(\n *         response=201,\n *         description="任务已创建",\n *         @OA\\JsonContent(ref="#/components/schemas/Task")\n *     )\n * )\n */\nfunction createTask() {\n    // 创建任务的逻辑\n    echo json_encode(['id' => 3, 'title' => '新任务', 'completed' => false]);\n}\n\n/**\n * @OA\\Schema(\n *     schema="Task",\n *     @OA\\Property(property="id", type="integer"),\n *     @OA\\Property(property="title", type="string"),\n *     @OA\\Property(property="completed", type="boolean")\n * )\n * @OA\\Schema(\n *     schema="TaskInput",\n *     @OA\\Property(property="title", type="string"),\n *     @OA\\Property(property