Swagger-PHP 使用指南：轻松为 PHP API 生成 OpenAPI 文档
项目地址: https://gitcode.com/gh_mirrors/sw/swagger-php 项目概述
Swagger-PHP 是一个强大的 PHP 工具，能够直接从你的 PHP 源代码中生成符合 OpenAPI 规范的 API 文档。它支持最新的 OpenAPI 3.0 和 3.1 版本，通过简单的注解或 PHP 8.1 属性，开发者可以轻松地为 RESTful API 生成详细的文档。
核心特性
-
完全兼容 OpenAPI 规范：生成的文档完全符合 OpenAPI 3.0 和 3.1 标准，确保与各种 API 工具无缝集成。
-
代码即文档：文档直接写在 PHP 源代码中，通过注释或属性标记，保持文档与代码同步更新，避免文档滞后问题。
-
双模式支持：同时支持传统的注解（Annotations）和 PHP 8.1 引入的属性（Attributes），适应不同项目需求。
快速入门
安装步骤
使用 Composer 进行安装是最简单的方式：
composer require zircote/swagger-php
代码标注
在你的 PHP 代码中添加 Swagger 标注。以下是两种方式的对比示例：
使用 PHP 8.1 属性（推荐）：
<?php
use OpenApi\Attributes as OA;
#[OA\Info(title: "我的API", version: "1.0")]
class OpenApiSpec {}
使用传统注解：
<?php
/**
* @OA\Info(title="我的API", version="1.0")
*/
class OpenApiSpec {}
注意：传统注解方式依赖 doctrine/annotations 包，未来可能会被弃用，建议新项目优先使用属性方式。
生成文档
安装完成后，使用以下命令生成 OpenAPI 文档：
./vendor/bin/openapi src -o openapi.yaml
这个命令会扫描 src 目录下的所有 PHP 文件，提取 Swagger 标注，并生成 openapi.yaml 文件。
查看与测试
生成的 OpenAPI 文档可以使用各种工具进行查看和测试，例如 Swagger UI 或 Redoc。这些工具可以提供交互式的 API 文档界面，方便开发者测试接口。
最佳实践
-
保持文档更新：每次修改 API 时，记得同步更新对应的 Swagger 标注。
-
详细描述：为每个接口、参数和响应添加详细的描述信息，方便其他开发者理解。
-
版本控制：将生成的 OpenAPI 文档纳入版本控制，方便追踪变更历史。
-
自动化集成：考虑将文档生成步骤集成到 CI/CD 流程中，确保文档始终最新。
进阶使用
Swagger-PHP 支持丰富的标注类型，可以描述：
- API 基本信息（标题、版本、描述等）
- 路径和操作（端点、HTTP 方法）
- 参数（查询参数、路径参数、请求体）
- 响应（状态码、返回数据结构）
- 安全方案（认证方式）
- 数据类型和模型
通过组合这些标注，你可以创建出非常详细的 API 文档，包括复杂的请求/响应模型和完整的业务逻辑描述。
总结
Swagger-PHP 为 PHP 开发者提供了一种简单高效的方式来创建和维护 API 文档。通过将文档与代码紧密结合，它解决了传统文档容易过时的问题，同时生成的标准化 OpenAPI 文档可以与各种 API 工具无缝集成。无论是小型项目还是大型企业级 API，Swagger-PHP 都是一个值得考虑的文档解决方案。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
