在 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 文档，这里就不再单独介绍了。

You are here

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

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

安装配置

通过注解对 API 进行描述

生成 API 文档

友情链接

搜索表单

用户登录

You are here

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

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

安装配置

通过注解对 API 进行描述

生成 API 文档

友情链接

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