PHP项目接口文档如何自动生成

本文目录导读：

1. Swagger/OpenAPI + 注解（最推荐）
2. ApiGen - 通过PHPDoc生成
3. Scribe（Laravel推荐）
4. Daux.io - 静态文档生成
5. 实战推荐方案
6. CI/CD自动集成
7. 推荐工具对比
8. 最佳实践建议

对于PHP项目接口文档的自动生成,我推荐以下几种主流方案：

Swagger/OpenAPI + 注解（最推荐）

使用方式：

/**
 * @OA\Get(
 *     path="/api/users/{id}",
 *     summary="获取用户信息",
 *     tags={"用户管理"},
 *     @OA\Parameter(
 *         name="id",
 *         in="path",
 *         required=true,
 *         @OA\Schema(type="integer")
 *     ),
 *     @OA\Response(
 *         response=200,
 *         description="成功返回用户信息",
 *         @OA\JsonContent(
 *             type="object",
 *             @OA\Property(property="id", type="integer"),
 *             @OA\Property(property="name", type="string"),
 *             @OA\Property(property="email", type="string")
 *         )
 *     )
 * )
 */
public function getUser($id)
{
    // 业务逻辑
}

工具链：

• zircote/swagger-php：生成OpenAPI规范
• Swagger UI：可视化文档界面
• L5-Swagger（Laravel专用）

ApiGen - 通过PHPDoc生成

/**
 * 获取用户列表
 *
 * @api {get} /api/users 获取用户列表
 * @apiName GetUsers
 * @apiGroup User
 * @apiVersion 1.0.0
 *
 * @apiParam {Number} [page=1] 页码
 * @apiParam {Number} [limit=20] 每页数量
 *
 * @apiSuccess {Number} code 状态码
 * @apiSuccess {String} message 提示信息
 * @apiSuccess {Object[]} data 用户列表
 */

Scribe（Laravel推荐）

composer require --dev knuckles/laravel-scribe
php artisan scribe:generate

自动生成：

• 基于路由和控制器自动提取
• 支持中间件、表单请求验证
• 生成Postman集合
• 生成Markdown/HTML文档

Daux.io - 静态文档生成

适合配合PHPDoc生成静态文档站点：

composer require --dev daux/daux.io

实战推荐方案

Laravel项目最佳实践：

1. 安装L5-Swagger
2. 在控制器添加注解
3. 配置生成命令到CI/CD

# 安装
composer require --dev darkaonline/l5-swagger
# 发布配置
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
# 生成文档
php artisan l5-swagger:generate

ThinkPHP/原生PHP方案：

1. 使用zircote/swagger-php
2. 配合Swagger UI使用

composer require --dev zircote/swagger-php
# 生成swagger.json
vendor/bin/openapi app/ -o public/swagger.json

CI/CD自动集成

# .github/workflows/docs.yml
name: Generate API Docs
on:
  push:
    branches: [main]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Generate Docs
        run: |
          composer install
          vendor/bin/openapi app/ -o docs/swagger.json
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

推荐工具对比

最佳实践建议

1. 接口文档vs代码同步：

   • 使用注解方式，文档紧贴代码
   • 纳入代码审查流程

2. 文档版本控制：

   • 接口版本：/api/v1/users
   • 文档版本：与API版本对应

3. 自动化部署：

   • CI/CD自动生成
   • 部署到独立的文档服务器

4. 团队规范：

   • 制定统一的注解规范
   • 编写注解模板
   • 定期review文档质量

强烈推荐方案：Swagger/OpenAPI + zircote/swagger-php，这是PHP生态中最成熟、最通用的方案，支持Laravel、ThinkPHP、Symfony等主流框架，且能很好地融入CI/CD流程。