在 Laravel 中集成 API 文档生成器扩展包为 Dingo API 接口生成文档

上篇教程学院君介绍了 Dingo 自带的 API 文档生成功能，除此之外，我们还可以基于 Laravel 生态的其它 API 文档生成扩展包为 Dingo API 生成文档。比如学院君之前发布的 使用 Laravel API 文档生成器扩展包自动为项目生成 API 文档 这篇教程使用的 laravel-apidoc-generator 扩展包就可以。

安装配置

安装完该扩展包后，按照教程中的介绍将配置文件 apidoc.php 发布到 config 目录下，如果要为 Dingo API 生成文档，需要将该配置文件中的 router 配置项修改为 dingo （默认是 laravel ，用于为 Laravel 路由生成接口文档），更多配置项的配置可以浏览该配置文件查看，每个配置都有完整的注释，你也可以查看 官方文档 去了解。

由于我们定义 Dingo API 时，设置了 v1、v2、v3 三个版本，所以我们将 routes 配置项中的 version 配置调整为支持所有版本：

'versions' => [
    'v1',
    'v2',
    'v3'
],

通过注解对 API 进行描述

和 Dingo 自带的 API 文档生成功能一样，API 文档生成器扩展包也是通过注解对 API 接口进行描述，然后运行 Artisan 命令根据这些注解信息生成对应的 API 文档，同样，该功能只支持通过控制器定义的 API 路由。

接下来我们修改 Api\TaskController 的注解信息如下：

...

/**
 * APIs For Task Resources
 * @package App\Http\Controllers\Api
 * @group 任务管理
 */
class TaskController extends ApiController
{
    public function __construct()
    {
        $this->middleware('auth:api');
    }

    /**
     * Task List
     *
     * @param Request $request
     * @return \Illuminate\Http\Response
     * @authenticated
     * @queryParam page required The number of the page. Example:1
     * @queryParam limit required Task items per page.Example:10
     * @responseFile responses/tasks.list.json
     */
    public function index(Request $request)
    {
        $limit = $request->input('limit') ? : 10;
        // 获取认证用户实例
        $user = $request->user('api');
        $tasks = Task::where('user_id', $user->id)->paginate($limit);
        return $this->response->paginator($tasks, new TaskTransformer());
    }

    /**
     * New Task
     *
     * @param  CreateTaskRequest $request
     * @return \Illuminate\Http\Response
     * @authenticated
     * @bodyParam text string required the body of task. Example: Test Task
     * @bodyParam is_completed boolean required task is completed or not. Example: 0
     * @responseFile responses/task.get.json
     */
    public function store(CreateTaskRequest $request)
    {
        $request->validate([
            'text' => 'required|string'
        ]);

        $task = Task::create([
            'text' => $request->post('text'),
            'user_id' => auth('api')->user()->id,
            'is_completed' => Task::NOT_COMPLETED
        ]);

        return $this->response->item($task, new TaskTransformer());
    }

    /**
     * Task Detail
     *
     * @param  int  $id
     * @return \Illuminate\Http\Response
     * @authenticated
     * @queryParam id required The id of the task. Example: 1
     * @responseFile responses/task.get.json
     * @responseFile 404 responses/task.not_found.json
     */
    public function show($id)
    {
        $task = Task::findOrFail($id);
        return $this->response->item($task, new TaskTransformer());
    }

    /**
     * Update Task
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  int  $id
     * @return \Illuminate\Http\Response
     * @authenticated
     * @queryParam id required The id of the task. Example:1
     * @bodyParam text string required the body of task. Example: Test Task
     * @bodyParam is_completed boolean required task is completed or not. Example: 1
     * @responseFile responses/task.get.json
     * @responseFile 404 responses/task.not_found.json
     */
    public function update(Request $request, $id)
    {
        $task = Task::findOrFail($id);
        $updatedTask = tap($task)->update(request()->only(['is_completed', 'text']))->fresh();
        return $this->response->item($updatedTask, new TaskTransformer());
    }

    /**
     * Delete Task
     *
     * @param  int  $id
     * @return \Illuminate\Http\Response
     * @authenticated
     * @queryParam id required The id of the task. Example: 1
     * @response {"message": "Task deleted"}
     * @response 404 {"message":"404 not found", "status_code": 404}
     */
    public function destroy($id)
    {
        $task = Task::findOrFail($id);
        $task->delete();
        return response()->json(['message' => 'Task deleted'], 200);
    }
}

我们可以对比着上篇教程 Dingo API 内置的注解指令来看：

@group
@authenticated
@queryParam
@bodyParam
@response

此外，还可以通过 @responseFile 从文件中获取返回的示例响应数据，这些保存示例数据的文件位于 storage/responses 目录下（通常是 JSON 文件），需要我们自己去创建并保存：

这样做的好处是对于复杂响应数据，可以避免控制器注解变得冗长，此外，如果多个 API 返回的数据格式相同，还可以实现示例数据的复用。

关于 API 文档生成器扩展包支持的注解命令我们就简单介绍到这里，更多使用方式可以参考 官方文档 。

生成 API 文档

为所有 Dingo 路由控制器设置好注解之后，就可以运行 API 文档生成器扩展包提供的 apidoc:generate 命令为 Dingo API 生成文档了：

php artisan apidoc:generate

该扩展包同样会跳过通过匿名函数定义的路由，只为通过控制器定义的 API 路由生成文档：

API 文档默认会生成到 public/docs 目录，所以我们可以在浏览器中通过 http://todo.test/docs/index.html 直接访问：

我们可以通过点击左侧的菜单快速在不同的接口文档之间切换（注意对应的控制器方法注释要包含英文字符，否则创建锚点的时候会失败，导致点击切换失效）。

此外，在 public/docs 目录下，还可以看到默认生成的 collection.json 文件，你可以将该文件导入到 Postman 里面以快速实现 API 接口的测试和使用：

如果是要为 Laravel API 生成文档，将 apidoc.php 配置文件中的 router 切换回 laravel ，注解定义方式完全一样，然后通过文档生成命令生成对应的 API 文档，这里就不再单独介绍了。