Swagger-PHP 使用教程

项目介绍

Swagger-PHP 是一个用于生成 OpenAPI 文档的 PHP 库。它允许开发者在 PHP 源代码中使用注解（annotations）或 PHP 8.1 的属性（attributes）来记录 API，从而生成符合 OpenAPI 规范的文档。Swagger-PHP 支持 OpenAPI 3.0 和 3.1 版本，并且可以通过 Composer 轻松安装和管理。

项目快速启动

安装

首先，通过 Composer 安装 Swagger-PHP：

composer require zircote/swagger-php

生成文档

在你的 PHP 项目中，使用以下代码生成 OpenAPI 文档：

require("vendor/autoload.php");

$openapi = \OpenApi\Generator::scan(['/path/to/your/project']);
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();

示例代码

在你的控制器或模型中添加注解：

use OpenApi\Annotations as OA;

/**
 * @OA\Info(title="My First API", version="0.1")
 */
class OpenApi {
}

class MyController {
    /**
     * @OA\Get(
     *     path="/users",
     *     @OA\Response(response="200", description="成功获取用户列表")
     * )
     */
    public function getUsers() {
        // 你的代码逻辑
    }
}

应用案例和最佳实践

应用案例

Swagger-PHP 广泛应用于需要生成 API 文档的 PHP 项目中。例如，一个电商平台的后端服务可以使用 Swagger-PHP 生成详细的 API 文档，供前端开发者和第三方开发者参考。

最佳实践

1. 保持文档更新：在代码中添加注解时，确保文档与代码同步更新，避免文档过时。
2. 使用属性（Attributes）：如果使用 PHP 8.1 或更高版本，推荐使用属性来替代注解，以提高代码的可读性和维护性。
3. 自动化文档生成：将文档生成过程集成到 CI/CD 流程中，确保每次代码提交后都能自动生成最新的 API 文档。

典型生态项目

Apifox

Apifox 是一个 API 一体化工具，可以帮助开发人员在一个平台上完成 API 设计、文档生成、管理和测试等多项任务。通过与 Swagger-PHP 结合使用，可以进一步提升 API 开发的效率和质量。

GitHub Actions

结合 GitHub Actions，可以在代码提交时自动生成和部署 API 文档。例如，可以创建一个 GitHub Actions 工作流，在每次 push 到主分支时自动运行 Swagger-PHP 生成文档，并将其部署到文档服务器。

通过以上内容，你可以快速上手并深入使用 Swagger-PHP，结合最佳实践和生态项目，提升你的 API 开发体验。