CatchAdmin 专业版文档

主题

接口 ​

最近看到社区很多项目都在使用注释/注解生成接口文档，本来从我个人角度来看，项目中使用这种方式还不如自己手动写接口。但是看到那么多人觉得这种方式很方便，我觉得还是自己来试试，没想到体验下来还真的觉得不错。IDE 加上 AI 补全，效率真的很高 😆。这多亏了 Laravel 丰富的社区，让我能体会到这种便捷性。

INFO

【Laravel scribe】 功能强大的注释接口文档生成包

WARNING

使用注释生成接口文档的功能，catchadmin/core 版本要大于等于 5.0

使用 ​

INFO

下面的对于该包的介绍，仅限在项目中使用到的，其实这个包有很强大的功能，如果 CatchAdmin 无法实现你对于功能的要求，可以通过它的文档来进行扩展

分组 ​

分组功能主要针对控制器，在控制器上使用对应的 Doc 注解 即可

php
/**
 * @group 公共模块
 *
 * @subgroup 地区管理
 * @subgroupDescription CatchAdmin 后台地区管理
 */
class AreaController
{
    //
}
  • @group 一级目录 (管理对应的控制器)
  • @subgroup 二级目录 （对应的就是控制器）
  • @subgroupDescription 二级目录描述

接口 ​

接口对应的就是控制器的方法，所以大部分的功能都是实现在这个上面，来看一个稍微复杂点的

php
/**
 * 更新用户
 *
 * @urlParam id int required 用户ID
 *
 * @bodyParam username string required 用户名
 * @bodyParam password string 密码
 * @bodyParam email string 邮箱
 * @bodyParam mobile string 手机号
 * @bodyParam department_id int 部门
 * @bodyParam roles integer[] 角色
 * @bodyParam jobs integer[] 职位
 *
 * @responseField data bool 是否更新成功
 *
 * @param $id
 * @param UserRequest $request
 * @return mixed
 */
public function update($id, UserRequest $request): mixed
{
    //
}
  • @urlParam path 参数 例如: /user/{id}
doc
@urlParam 字段名 类型  [required(可选)] 注释
  • @bodyParam body 参数，实际就是表单对应的部分
doc
@bodyParam 字段名 类型 [required(可选)] 注释
  • @responseField 响应的字段
doc
@responseField 字段名 类型 注释
  • @queryParam query 参数，例如: /user?page=1&limit=1
doc
@queryParam 字段名 类型  [required(可选)] 注释

INFO

如果添加了 required，则表示该字段必填，如果没有，则表示可选

参数对应的有效类型 ​

  • string 字符串
  • integer 整型
  • number 数字
  • boolean bool
  • object 对象
  • file 文件
  • [] 数组 例如 integer[], string[]

认证 ​

默认 CatchAdmin 后台接口都需要授权的，如果生成文档的时候不需要授权，可以这么使用

php
/**
 * 登录
 *
 * @unauthenticated
 *
 */
public function login(Request $request, AuthService $auth): array
{
    // 登录
}
  • @unauthenticated 使用该 Docblock 即可自动在文档标记

生成文档 ​

CatchAdmin 提供了非常简单命令，生成专业版对应的接口文档。如果你开发的后台是基于 CatchAdmin 模块模式开发的，那么这个命令可以帮你一键生成。 但是如果你想生成 C 端的对应的接口文档，则需要自己使用原始包来生成，因为生成对应的文档需要一定规则。你可以根据自己的项目设置。CatchAdmin 生成接口文档都有一些预配置。你可以查看 config/catch_api_doc.php 配置文件

shell
php artisan catch:api:doc

使用该命令，会在项目的根目录 api-doc 文件夹中生成接口文档细则。api-doc 是基于 Vitepress 生成的文档站点，生成接口之后，安装 vitepress 的依赖

php
yarn install

// 启动文档
yarn docs:dev

启动之后，你会看到这样的站点 CatchAdmin 专业版接口文档

导入到 Apifox ​

如果你需要类似 apifox 这样的客户端，可以在使用 php artisan catch:api:doc 命令之后，也同时会在 api-doc 根目录下生成 postman.json 元数据文件。

如图所示

CatchAdmin 专业版接口文档

项目设置 > 导入数据

选择 Postman，点击 导入 该 Json 文件即可