msf 生成php马_Laravel 集成 API文档生成器扩展包为 Dingo API 接口

最新推荐文章于 2024-05-14 17:07:48 发布

weixin_39783149

最新推荐文章于 2024-05-14 17:07:48 发布

阅读量155

点赞数

文章标签： msf 生成php马 rouyi 接口异常 404

安装配置

安装完该扩展包后，将配置文件 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 直接访问：我们可以通过点击左侧的菜单快速在不同的接口文档之间切换(注意对应的控制器方法注释要包含英文字符，否则创建锚点的时候会失败，导致点击切换失效)。

此外，在 public/docs 目录下，还可以看到默认生成的 collection.json 文件，你可以将该文件导入到 Postman 里面以快速实现 API 接口的测试和使用：如果是要为 Laravel API 生成文档，将 apidoc.php 配置文件中的 router 切换回 laravel，注解定义方式完全一样，然后通过文档生成命令生成对应的 API 文档，这里就不再单独介绍了。