Swagger/OpenAPI 生成用于 PHP：最佳工具和库

Swagger/OpenAPI 生成用于 PHP：API 文档自动化

Swagger（现为 OpenAPI）是一种描述 RESTful API 的标准，它允许开发者、客户端和自动化工具无需访问源代码即可理解服务的功能。对于 PHP 开发者来说，关键工具是 zircote/swagger-php 库（以前称为 swagger-php），它可以根据代码中的注释自动生成 OpenAPI 规范。

什么是 zircote/swagger-php？

这是用于在 PHP 中生成 OpenAPI 规范的主要库。它分析控制器、模型和路由中的 PHPDoc 注释，生成一个 JSON/YAML 文件，可用于：

• 自动生成文档（Swagger UI, ReDoc）
• 为不同语言生成客户端库
• API 测试（Postman, Insomnia）
• 请求和响应的验证

安装和配置

通过 Composer 安装：

composer require zircote/swagger-php

Laravel（或任何框架）的最小配置包括在控制器中创建注释。一个带有 OpenAPI 注释的简单控制器示例：

<?php

namespace App\\Http\\Controllers\\Api;

use OpenApi\\Annotations as OA;

/** * @OA\\Info(title="My API", version="1.0.0") * @OA\\Server(url="https://api.example.com") */class UserController extends Controller{    /**     * @OA\\Get(     *     path="/api/users/{id}",     *     summary="根据 ID 获取用户",     *     @OA\\Parameter(     *         name="id",     *         in="path",     *         required=true,     *         @OA\\Schema(type="integer")     *     ),     *     @OA\\Response(     *         response=200,     *         description="成功响应",     *         @OA\\JsonContent(ref="#/components/schemas/User")     *     ),     *     @OA\\Response(response=404, description="未找到用户")     * )     */    public function show($id)    {        // 逻辑    }}

生成规范

要创建 OpenAPI 文件，请执行命令：

vendor/bin/openapi src -o public/openapi.yaml

或者使用 PHP 代码：

<?php

use OpenApi\\Generator;

$openapi = Generator::scan(['/path/to/project/src']);file_put_contents('public/openapi.json', $openapi->toJson());

高级功能

该库支持：

• 嵌套模式 — 从注释自动创建模型
• 端点分组 — 通过 @OA\\Tag
• 安全性 — 用于 JWT、OAuth2 的 @OA\\SecurityScheme
• 请求示例 — 带有示例的 @OA\\RequestBody

带有注释的模型示例：

<?php

/** * @OA\\Schema( *     schema="User", *     required={"id", "email"}, *     @OA\\Property(property="id", type="integer", format="int64"), *     @OA\\Property(property="email", type="string", format="email"), *     @OA\\Property(property="name", type="string"), *     @OA\\Property(property="created_at", type="string", format="date-time") * ) */class User{    // 属性}

与框架的集成

对于 Laravel，有 darkaonline/l5-swagger 包，它增加了：

• 每次请求时自动生成
• 内置 Swagger UI
• 通过配置文件进行配置

安装：

composer require darkaonline/l5-swaggerphp artisan vendor:publish --provider="L5Swagger\\L5SwaggerServiceProvider"

对于 Symfony，请使用 nelmio/api-doc-bundle。

比较