Laravel Api Documentation

如何生成api的使用文档：

比如Blogger的Api这样的：

方便你的用户来阅读使用。

参考：https://laravel-apidoc-generator.readthedocs.io/en/latest/index.html

执行：

composer require mpociot/laravel-apidoc-generator

执行：

php artisan vendor:publish --provider="Mpociot\ApiDoc\ApiDocGeneratorServiceProvider" --tag=apidoc-config

参考Generating Documentation

执行：

php artisan apidoc:generate

生成的文件位置：

浏览器打开：http://laravelauth.test/docs/ 即可查看

修改测试：

修改 Welcome to the generated API reference. 为 欢迎来到Api文档 。

然后参考Manually modifying the content of the generated documentation   执行：

php artisan apidoc:rebuild

效果如下：

接下来参考：Documenting Your API

要给控制器分组，我们在目标控制器类前添加：

/**
 * @group User management
 *
 * APIs for managing users
 */

@group是必须的，文本就自定义了。

比如在TaskController之前我们定义：

修改完成后，执行

php artisan apidoc:generate

接着打开http://laravelauth.test/docs/即可看到：

多出来一个叫做 Tasks management 的分组，注解为 APIs for managing tasks。

接下来参考 Specifying request parameters 对TaskController里面的方法进行注解；

store方法：

参考在postman中发送的参数要求

最好是看migration

我们需要的body参数有：title【必须】description，due其余的都是可选的。

所以添加：

@bodyParam title string required 任务的标题. Example: 处理剩余的什麽.

其余的可选的就不用required，类型按照需要的类型提供即可

@bodyParam description text 任務的描述. Example:描述這個任務是做什麽
@bodyParam due string 任務的截至日.Example: next monday

然后执行：

php artisan apidoc:generate

打开 http://laravelauth.test/docs/ 查看：

剩余的方法如何写就不再讲述。

摘一段官方讲解：

Specifying request parameters

To specify a list of valid parameters your API route accepts, use the @urlParam, @bodyParam and @queryParam annotations.

The @urlParam annotation is used for describing parameters in your URl. For instance, in a Laravel route with this URL: “/post/{id}/{lang?}”, you would use this annotation to describe the id and lang parameters. It takes the name of the parameter, an optional “required” label, and then its description.
The @queryParam annotation takes the name of the parameter, an optional “required” label, and then its description.
The @bodyParam annotation takes the name of the parameter, its type, an optional “required” label, and then its description.

response注解：

store方法

参考：Providing an example response

返回的内容可以复制postman的结果

修改一下：

* @response {
*  "data": {
*      "title": "due task",
*      "description": "task with due date",
*      "due": "2020-04-19 00:00:00",
*      "user_id": 1,
*      "updated_at": "2020-04-14T07:20:02.000000Z",
*      "created_at": "2020-04-14T07:20:02.000000Z",
*      "id": 11,
*      "user": {
*          "id": 1,
*          "name": "user",
*          "email": "user@user.com",
*          "email_verified_at": null,
*          "created_at": "2020-04-14T05:42:55.000000Z",
*          "updated_at": "2020-04-14T05:42:55.000000Z",
*          "deleted_at": null
*    }
*  }
* }

/**
 * Store a newly created task in storage.
 * @bodyParam title string required 任务的标题. Example: 处理剩余的什麽
 * @bodyParam description text 任務的描述. Example:描述這個任務是做什麽
 * @bodyParam due string 任務的截至日.Example: next monday
 * @param \Illuminate\Http\Request $request
 * @response {
 *  "data": {
 *      "title": "due task",
 *      "description": "task with due date",
 *      "due": "2020-04-19 00:00:00",
 *      "user_id": 1,
 *      "updated_at": "2020-04-14T07:20:02.000000Z",
 *      "created_at": "2020-04-14T07:20:02.000000Z",
 *      "id": 11,
 *      "user": {
 *          "id": 1,
 *          "name": "user",
 *          "email": "user@user.com",
 *          "email_verified_at": null,
 *          "created_at": "2020-04-14T05:42:55.000000Z",
 *          "updated_at": "2020-04-14T05:42:55.000000Z",
 *          "deleted_at": null
 *    }
 *  }
 * }
 */
public function store(Request $request)
{
    $validated = Validator::make($request->all(), [
        'title' => 'required|max:255',
    ]);
    if ($validated->fails()) {
        return response($validated->errors()->all());
    }
    $input = $request->all();
    if ($request->has('due')) {
        $input['due'] = Carbon::parse($request->get('due'))->toDateTimeString();
    }
    $task = auth()->user()->tasks()->create($input);

    return new TaskResource($task->load('user'));
}

执行：

php artisan apidoc:generate

打开 http://laravelauth.test/docs/ 查看：

其余的参考Providing an example response。

如果有apiResource的 虽然可以自己生成，但是并不完整。建议采用 @responseFile 。

<?php

namespace App\Http\Controllers;

use App\Http\Resources\TaskResource;
use App\Task;
use Illuminate\Http\Request;
use Illuminate\Support\Carbon;
use Illuminate\Support\Facades\Validator;

/**
 * @group Tasks management
 *
 * APIs for managing tasks
 */
class TaskController extends Controller
{
    /**
     * Display a listing of the tasks.
     *
     * @return \Illuminate\Http\Response
     */
    public function index()
    {
        //
        $tasks = TaskResource::collection(auth()->user()->tasks()->with('user')->latest()->paginate(4));
        return response($tasks, 200);
    }

    /**
     * Store a newly created task in storage.
     * @bodyParam title string required 任务的标题. Example: 处理剩余的什麽
     * @bodyParam description text 任務的描述. Example:描述這個任務是做什麽
     * @bodyParam due string 任務的截至日.Example: next monday
     * @param \Illuminate\Http\Request $request
     * @response {
     *  "data": {
     *      "title": "due task",
     *      "description": "task with due date",
     *      "due": "2020-04-19 00:00:00",
     *      "user_id": 1,
     *      "updated_at": "2020-04-14T07:20:02.000000Z",
     *      "created_at": "2020-04-14T07:20:02.000000Z",
     *      "id": 11,
     *      "user": {
     *          "id": 1,
     *          "name": "user",
     *          "email": "user@user.com",
     *          "email_verified_at": null,
     *          "created_at": "2020-04-14T05:42:55.000000Z",
     *          "updated_at": "2020-04-14T05:42:55.000000Z",
     *          "deleted_at": null
     *    }
     *  }
     * }
     * @response 401 {
     *  "message":"The field is required."
     * }
     */
    public function store(Request $request)
    {
        $validated = Validator::make($request->all(), [
            'title' => 'required|max:255',
        ]);
        if ($validated->fails()) {
            return response($validated->errors()->all(), 401);
        }
        $input = $request->all();
        if ($request->has('due')) {
            $input['due'] = Carbon::parse($request->get('due'))->toDateTimeString();
        }
        $task = auth()->user()->tasks()->create($input);

        return new TaskResource($task->load('user'));
    }

    /**
     * Display the specified resource.
     * @urlParam task int required The ID of the task.
     * @response {
     *  "data": {
     *      "title": "due task",
     *      "description": "task with due date",
     *      "due": "2020-04-19 00:00:00",
     *      "user_id": 1,
     *      "updated_at": "2020-04-14T07:20:02.000000Z",
     *      "created_at": "2020-04-14T07:20:02.000000Z",
     *      "id": 11,
     *      "user": {
     *          "id": 1,
     *          "name": "user",
     *          "email": "user@user.com",
     *          "email_verified_at": null,
     *          "created_at": "2020-04-14T05:42:55.000000Z",
     *          "updated_at": "2020-04-14T05:42:55.000000Z",
     *          "deleted_at": null
     *    }
     *  }
     * }
     *
     * @response 404 {
     *  "message":"Not Found"
     * }
     */
    public function show(Task $task)
    {
        //
        return new TaskResource($task->load('user'));
    }

    /**
     * Update the specified resource in storage.
     * @urlParam task int required The ID of the task.
     * @bodyParam title string required 任务的标题. Example: 处理剩余的什麽
     * @bodyParam description text 任務的描述. Example:描述這個任務是做什麽
     * @bodyParam due string 任務的截至日.Example: next monday
     * @response {
     *  "data": {
     *      "title": "due task",
     *      "description": "task with due date",
     *      "due": "2020-04-19 00:00:00",
     *      "user_id": 1,
     *      "updated_at": "2020-04-14T07:20:02.000000Z",
     *      "created_at": "2020-04-14T07:20:02.000000Z",
     *      "id": 11,
     *      "user": {
     *          "id": 1,
     *          "name": "user",
     *          "email": "user@user.com",
     *          "email_verified_at": null,
     *          "created_at": "2020-04-14T05:42:55.000000Z",
     *          "updated_at": "2020-04-14T05:42:55.000000Z",
     *          "deleted_at": null
     *    }
     *  }
     * }
     *
     * @response 404 {
     *  "message":"Not Found"
     * }
     * @response 401 {
     *  "message":"The field is required."
     * }
     *
     * @response 422 {
     *  "message": "No permission!"
     * }
     * @param \Illuminate\Http\Request $request
     *
     *
     */
    public function update(Request $request, Task $task)
    {
        //
        $validated = Validator::make($request->all(), [
            'title' => 'required|max:255',
        ]);
        if ($validated->fails()) {
            return response($validated->errors()->all());
        }

        if (!auth()->user()->tasks->contains($task)) {
            return response('No permission!', 422);
        }
        $input = $request->all();

        if ($request->has('due')) {
            $input['due'] = Carbon::parse($request->get('due'))->toDateTimeString();
        }
        $task->update($input);

        return new TaskResource($task->load('user'));

    }

    /**
     * Remove the specified resource from storage.
     * @urlParam task int required The ID of the task.
     * @response {
     *  "message": "Success deleted!"
     *  }
     * @response 404 {
     *  "message":"Not Found"
     * }
     * @return \Illuminate\Http\Response
     */
    public function destroy(Task $task)
    {
        //
        if (!auth()->user()->tasks->contains($task)) {
            return response('No permission!', 422);
        }
        $task->delete();

        return response(['message' => 'Success deleted!']);
    }
}

当前生成的文档：

包含这个general的我们并不需要。

如果需要在生成的时候，只生成api的 在apidoc.php中做如下修改：

修改前：

修改后：

执行：

php artisan apidoc:generate

然后打开http://laravelauth.test/docs/ 可以看到general 没有了，只有route路由为api/task对应的Controller【即：TaskController】生成了文档：