Laravel Apidoc接口文档工具

foryoufeng
19 阅读4分钟

logo.png

Laravel Apidoc

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

项目地址

github.com/larafly/api…

演示地址：

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 即可看到生成的文档文件

avatar
文章
阅读
粉丝