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

由学院君创建于4年前, 最后更新于 4年前版本号 #1 11448 views 1 likes 0 collects

上篇教程学院君介绍了 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 注解用于对 API 进行分组，以便在生成的文档中按照该注解对 API 进行归档，看起来更加方便；
@authenticated 注解表示该接口需要认证后才能访问；
@queryParam 注解用于描述 API 接口的 URL 查询字符串参数，我们可以定义参数名、是否必须（不设置 required 表示可选）、参数含义、示例数据，多个参数需要定义多个注解；
@bodyParam 注解用于描述 API 接口通过请求实体传递的参数，我们可以定义字段名、数据类型、是否必须（不设置 required 表示可选）、参数含义、示例数据，多个字段需要定义多个注解；
@response 注解用于定义接口返回的实例数据，默认响应状态码是 200，如果是其他情况，需要手动指定该状态码，如果响应数据有多种情况需要指定多个注解。

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