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

此外,还可以通过 @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 直接访问:

Laravel API 文档生成器 + Dingo API

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

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

Postman 导入 Collection 测试 API 接口

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

上一篇: 使用 Laravel API 文档生成器扩展包自动为项目生成 API 文档

下一篇: 在 Laravel 项目中集成 Swagger 扩展包为 Laravel API 生成接口文档并对接口进行测试