PHP调用Swagger生成接口文档

本文详细介绍了如何在PHP项目中利用Swagger（OpenAPI规范）通过代码注解自动生成并展示交互式API文档，涵盖从Composer安装swagger-php、扫描注解生成openapi.json，到在控制器中编写标准化@OA注解描述接口路径、参数、响应及数据模型，最后集成swagger-ui实现可视化、可在线调试的实时文档；整个流程确保文档与代码高度同步，显著提升前后端协作效率与API维护质量。

PHP项目中调用API并生成接口文档，使用Swagger（现为OpenAPI Initiative）是一种高效且标准化的方式。通过注解或代码配置，Swagger能自动生成可视化、可测试的API文档，极大提升前后端协作效率。

1. 使用Swagger在PHP中生成接口文档

Swagger支持通过代码中的注释（注解）来描述API结构，结合工具如swagger-php和swagger-ui，可以自动扫描PHP代码并生成符合OpenAPI规范的JSON/YAML文件，最终渲染成网页版交互式文档。

基本流程如下：

• 在PHP代码中使用注释编写API元数据（如路径、参数、返回值等）
• 使用swagger-php解析注释，生成openapi.json或openapi.yaml
• 将生成的文件接入swagger-ui展示为可视化页面

2. 安装与配置Swagger工具

通过Composer安装swagger-php：

composer require zircote/swagger-php

安装完成后，在项目根目录运行命令扫描注释：

vendor/bin/openapi src/ -o openapi.json

上述命令会扫描src/目录下所有含Swagger注解的PHP文件，并输出为openapi.json。

3. 在PHP代码中编写Swagger注解

以Laravel或原生PHP为例，在控制器方法上添加注解：

/**
 * @OA\Get(
 *     path="/api/users",
 *     summary="获取用户列表",
 *     tags={"用户"},
 *     @OA\Response(
 *         response=200,
 *         description="成功返回用户数组",
 *         @OA\JsonContent(
 *             type="array",
 *             @OA\Items(ref="#/components/schemas/User")
 *         )
 *     )
 * )
 */
public function getUsers()
{
    return User::all();
}

常见注解说明：

• @OA\Get / @OA\Post：定义HTTP方法和路径
• @OA\Parameter：描述请求参数（query/body等）
• @OA\Schema / @OA\Property：定义数据模型结构
• @OA\Response：描述响应格式和状态码

4. 集成Swagger UI展示文档

下载或通过CDN引入swagger-ui，将其部署到项目中（如public/docs目录），然后修改index.html中的URL指向生成的openapi.json：

url: "http://your-api.com/openapi.json"

访问http://your-project.com/docs即可查看交互式API文档，支持在线测试接口。

基本上就这些。只要写好注释，每次更新接口后重新生成JSON，文档就能保持同步，不复杂但容易忽略细节。

好了，本文到此结束，带大家了解了《PHP调用Swagger生成接口文档》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！