Laravel Apidoc

Laravel Apidoc 是一个基于 Laravel 的Api接口文档生成工具

项目地址

github.com/larafly/apidoc

演示地址：

larafly-demo.pp-lang.tech/apidoc

安装

通过 Composer 进行安装

composer require larafly/apidoc

运行如下命令来安装接口文档工具

php artisan apidoc:install

现在你可以访问您的应用urlhttp://localhost:8000/apidoc 来使用Laravel Apidoc了

配置文件

发布配置文件

php artisan vendor:publish --tag=larafly-apidoc

larafly-apidoc.php 文件说明

 <?php return [ # 接口文档访问地址 'route' => env('API_DOC_ROUTE', 'apidoc'), # 格式化日期 'datetime_format' => 'Y-m-d H:i:s', # 接口文档撰写人 'author' => env('GENERATOR_AUTHOR', 'system'), # 生产环境是否显示文档，默认为不显示 'is_show' => env('API_DOC_SHOW', false), ]; 

在.env中配置GENERATOR_AUTHOR=您的名字，来进行创建人的配置

生成Request

使用命令行生成Request类

php artisan apidoc:request UserRequest

如果您继承分页的类PageApiRequest，可以加上--p

php artisan apidoc:request UserRequest --p

请求类示例

HomeController的index请求参数中定义UserLogRequest $request请求类

<?php namespace App\Http\Controllers\Home; use Larafly\Apidoc\Attributes\Api; use Larafly\Apidoc\Attributes\Group; #[Group('用户管理',parent_name:'用户',module:'Home')] class UserController extends Controller { #[Api('列表页',desc:"用户列表数据")] public function index(UserLogRequest $request) { ... } #[Api('详情页')] public function show() { ... } #[Api('更新',desc:'改接口即将废弃,已不建议使用')] public function update() { ... } }

说明

属性定义

• Larafly\Apidoc\Attributes\Group 定义接口分类所属组的属性
• Larafly\Apidoc\Attributes\Api 定义接口名称的属性

属性说明：

• #[Group('用户管理')]：用于定义接口分类所属组，多层级分组可使用 / 进行区分，如 #[Group('订单/发货管理')]
• #[Group('用户管理',parent_name:'用户',module:'Home')]：parent_name表示组所属的父级分组,module表示api接口所属的板块，不设置默认以namespace App\Http\Controllers\Home;中的Home为模块
• 可通过访问http://localhost:8000/apidoc/home 来访问对应的模块
• #[Api('详情页')]：用于定义api接口的名称，
  • #[Api('列表页',desc:"用户列表数据")] 如需对接口进行说明，可使用desc参数

在App\Http\Requests\UserLogRequest定义好请求参数的 Larafly\Apidoc\Attributes\Prop

<?php namespace App\Http\Requests; use Larafly\Apidoc\Attributes\Prop; use Larafly\Apidoc\Requests\PageApiRequest; class UserLogRequest extends PageApiRequest { #[Prop('用户id')] public int $user_id; #[Prop('用户名称')] public ?string $name; public function rules(): array { $rules = parent::rules(); return array_merge($rules, [ 'user_id' => 'int', 'name' => 'nullable|string|max:3', ]); } public function messages(): array { $messages = parent::messages(); return array_merge($messages, [ 'user_id' => '用户id不能为空', 'name.max' => '名称不能超过3', ]); } } 

属性定义

• Larafly\Apidoc\Attributes\Prop 定义请求参数的属性

属性说明：

• #[Prop('用户id')]：用于对该属性字段进行说明
• 以下说明请求参数为user_id,字段类型为int,参数必填，user_name为string，不必填，属性前加上?表示该字段必填

#[Prop('用户id')] public int $user_id; #[Prop('用户名称')] public ?string $name; 

Larafly\Apidoc\Requests\PageApiRequest 默认设置了分页的请求属性page=1和per_page=10

<?php namespace Larafly\Apidoc\Requests; use Larafly\Apidoc\Attributes\Prop; class PageApiRequest extends ApiRequest { #[Prop(desc: '页码,最小为1')] public ?int $page = 1; #[Prop(desc: '每页条数,最小为10，最大为100')] public ?int $per_page = 10; public function rules(): array { return [ 'page' => ['nullable', 'integer', 'min:1'], 'per_page' => ['nullable', 'integer', 'min:10', 'max:100'], ]; } public function messages(): array { return [ 'page.min' => '页码必须大于1', 'per_page.min' => '每页数必须大于10', 'per_page.max' => '每页数不能超过100', ]; }

生成Response

使用命令行生成Response类

php artisan apidoc:response UserResponse

如果您继承分页的类PaginateResponse，可以加上--p

php artisan apidoc:response UserResponse --p

响应示例

HomeController的index返回参数中定义UserLogPaginateResponse响应类

<?php namespace App\Http\Controllers; use Larafly\Apidoc\Attributes\Api; use Larafly\Apidoc\Attributes\Group; use App\Http\Requests\UserLogRequest; use App\Http\Daos\UserLogDao; #[Group('用户管理')] class HomeController extends Controller { #[Api('列表页',desc:"用户列表数据")] public function index(UserLogRequest $request): UserLogPaginateResponse { return $this->userLogDao->getList($request->name, $request->per_page); } }

在App\Http\Daos\UserLogDao的处理

<?php namespace App\Http\Daos; use App\Enums\UserTypeEnum; use App\Http\Responses\UserLogPaginateResponse; use App\Models\UserLog; class UserLogDao { public function getList(string $name='', int $per_page=10): UserLogPaginateResponse { $data = UserLog::with('user') ->when($name, fn ($q) => $q->where('name', 'like', "%$name%")) ->paginate($per_page); return UserLogPaginateResponse::success($data); } 

在App\Http\Responses\UserLogPaginateResponse定义好接口返回参数的 Larafly\Apidoc\Attributes\Prop

<?php namespace App\Http\Responses; use Larafly\Apidoc\Attributes\Prop; use Larafly\Apidoc\Responses\PaginateResponse; class UserLogPaginateResponse extends PaginateResponse { #[Prop(desc: '记录id')] public int $id; #[Prop(desc: '名称')] public string $name; }

属性定义

• Larafly\Apidoc\Attributes\Prop 定义接口返回参数的属性

属性说明：

• #[Prop('记录id')]：用于对该属性字段进行说明
• 以下说明返回参数为id,字段类型为int,说明为记录id，name为string，说明为名称

#[Prop('用户id')] public int $id; #[Prop('名称')] public string $name;

Larafly\Apidoc\Responses\PaginateResponse; 默认设置了返回分页的响应的meta数据

{ "code": 200, "data": [ { "id": 1, "name": "John Doe" }, { "id": 1, "name": "John Doe" } ], "message": "success", "meta": { "current_page": 1, "last_page": 10, "per_page": 10, "total": 100 } }

生成命令

1. 文档写入数据库,运行如下命令

php artisan apidoc

生成完毕后,访问http://localhost:8000/apidoc 即可看到生成的文档，如生成的有问题，可检查相关接口配置是否定义好

2. 文档写入markdown文件中,可运行如下命令

php artisan apidoc:md

生成完毕后,访问storage/app/public/apidoc 即可看到生成的文档文件

本作品采用《CC 协议》，转载必须注明作者和本文链接