Swagger/OpenAPI 生成用于 PHP

Swagger/OpenAPI 生成用于 PHP：工具全面概览

在现代 Web 开发中，创建高质量的 API 文档已不仅仅是良好习惯，而是一种必要。Swagger（现称为 OpenAPI）是一种描述 RESTful API 的标准，它允许自动化生成文档、客户端 SDK 和测试控制台界面。在本文中，我们将详细探讨如何在 PHP 项目中使用 Swagger/OpenAPI，有哪些可用的库，以及如何正确集成它们。

什么是 Swagger/OpenAPI？

OpenAPI 规范 (OAS) 是一种定义 REST API 描述标准（JSON 或 YAML 格式）的规范。它允许：

自动生成交互式文档（Swagger UI）；
为不同编程语言创建客户端库；
验证请求和响应的正确性；
与 CI/CD 流水线集成。

PHP 的主要库

在 PHP 中处理 OpenAPI 有几个流行的库。我们来逐一详细了解它们。

1. Swagger-PHP (zircote/swagger-php)

这是最流行且成熟的库，用于从 PHP 注解生成 OpenAPI 规范。它允许直接在代码中描述 API，从而简化了文档的实时维护。

安装：

composer require zircote/swagger-php

使用示例：

<?phpuse OpenApi\\Annotations as OA;

/** * @OA\\Info( *     title="我的 API", *     version="1.0.0", *     description="用于演示 Swagger 的示例 API" * ) * @OA\\Server( *     url="https://api.example.com", *     description="生产服务器" * ) */class UserController{    /**     * @OA\\Get(     *     path="/api/users",     *     summary="获取用户列表",     *     @OA\\Response(     *         response=200,     *         description="成功响应",     *         @OA\\JsonContent(type="array",     *             @OA\\Items(ref="#/components/schemas/User")     *         )     *     )     * )     */    public function getUsers()    {        // 获取用户的逻辑    }

    /**     * @OA\\Schema(     *     schema="User",     *     type="object",     *     @OA\\Property(property="id", type="integer"),     *     @OA\\Property(property="name", type="string"),     *     @OA\\Property(property="email", type="string")     * )     */    public function userSchema()    {        // 用于描述模式的空方法    }}

// 生成规范$openapi = \\OpenApi\\Generator::scan(['/path/to/controllers']);file_put_contents('openapi.json', $openapi->toJson());?>

2. OpenAPI-Server (thecodingmachine/openapi-server)

这个库不仅允许描述 API，还能根据 OpenAPI 规范自动生成服务器端代码。在使用 Design-First 开发原则时尤其有用。

安装：

composer require thecodingmachine/openapi-server

服务器生成示例：

<?phpuse TheCodingMachine\\OpenAPI\\Server\\Builder;

// 加载规范$spec = json_decode(file_get_contents('openapi.json'), true);

// 创建服务器$builder = new Builder();$server = $builder->build($spec, 'App\\\\Controllers\\\\');

// 处理请求$response = $server->handle($request);?>