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

1. 这是什么及为何需要它

Swagger-PHP 是一个强大的 PHP 语言库，它允许您基于代码中的注解自动生成 REST API 的 OpenAPI（原 Swagger）规范。无需手动编写描述所有端点、参数、数据模型和响应的庞大 YAML 或 JSON 文件，您只需在 PHP 应用程序的控制器、模型和路由中直接添加特殊的注释（注解）。该库会分析这些注解，并生成一个完整、有效的 OpenAPI 规范，可以导出为 JSON 或 YAML 格式。

为什么需要它？在现代 Web 开发中，API 是前端、移动应用和第三方服务之间交互的关键接口。保持文档与实际状态一致是一个持续的难题。Swagger-PHP 通过将文档直接与源代码关联来解决这个问题。如果您更改了端点的逻辑，您也会更改其旁边的注解。文档始终与 API 的实际行为保持一致。这节省了数小时的工作时间，减少了集成错误的数量，并使您的项目对新开发人员更加透明。

此外，生成的 OpenAPI 规范可以与数十种工具一起使用：Swagger UI（交互式文档，您可以直接在浏览器中测试请求）、用于 JavaScript、Python、Java 等语言的客户端 SDK 生成器、用于测试和验证的工具（例如 Postman 或 Insomnia），以及用于自动生成模拟服务器的工具。Swagger-PHP 是记录 PHP API 的事实标准。

2. 安装

通过 Composer（PHP 的标准包管理器）进行安装。在项目根目录下执行以下命令：

composer require zircote/swagger-php

安装后，您的项目中会出现 vendor/zircote/swagger-php 目录。该库需要 PHP 8.0 或更高版本（以支持现代 PHP 8 属性的注解）。如果您使用的是较旧版本的 PHP，则需要使用该库的 3.x 版本，但强烈建议升级到 PHP 8+ 并使用最新版本的 Swagger-PHP (4.x)。

3. 快速入门 — 最小工作示例

让我们创建一个包含一个端点的简单控制器，并为其生成 OpenAPI 规范。

步骤 1：创建文件 src/Controllers/UserController.php

<?php\n\nnamespace App\\Controllers;\n\nuse OpenApi\\Attributes as OA;\n\nclass UserController\n{\n    #[OA\\Get(\n        path: '/api/users/{id}',\n        summary: '根据 ID 获取用户',\n        tags: ['Users']\n    )]\n    #[OA\\Parameter(\n        name: 'id',\n        in: 'path',\n        required: true,\n        schema: new OA\\Schema(type: 'integer')\n    )]\n    #[OA\\Response(\n        response: 200,\n        description: '成功响应',\n        content: new OA\\JsonContent(\n            properties: [\n                new OA\\Property(property: 'id', type: 'integer'),\n                new OA\\Property(property: 'name', type: 'string'),\n                new OA\\Property(property: 'email', type: 'string')\n            ]\n        )\n    )]\n    public function getUser(int $id): array\n    {\n        // 这里应该是从数据库获取用户的逻辑\n        return [\n            'id' => $id,\n            'name' => 'John Doe',\n            'email' => 'john@example.com'\n        ];\n    }\n}

步骤 2：创建用于生成规范的脚本 generate-docs.php

<?php\n\nrequire_once __DIR__ . '/vendor/autoload.php';\n\nuse OpenApi\\Generator;\n\n// 指定包含我们