接口文档生成

CabalPHP 支持接口文档自动生成。

编写好相关配置和文档注释后浏览器访问 http://127.0.0.1:9501/__docs 即可查看相关文档，注意检查自己的监听端口和IP。

点击这里访问示例文档

?> 接口文档地址只能在debug环境（cabal.debug配置为true）下访问。

配置

文档相关配置在 conf/cabal.php

  1.     // ... 
  2.     'document' => [
  3.         // 是否启用文档，默认为 true
  4.         // 'enabled' => true,  
  5.         // 使用 知乎的 unpkg cdn，默认为 unpkg.com 没有国内节点，速度较慢。知乎的为国内节点，但是并不是官方公开的源，目前可外链，稳定性未知
  6.         'cdn' => 'unpkg.zhimg.com',
  7.         // 文档页面的项目名称
  8.         'name' => 'CabalPHP',
  9.     ],
  10.     // ...

使用方法

系统会自动根据你的路由配置，解析控制器方法的注释，自动生成生成，文档更新同样需要reload或者restart服务器。

如果控制器继承自 Cabal\Core\Base\FilterController 系统会读取接口参数约束配置生成文档（接口参数的“约束”列）。
详情可查看 路由 & 控制器 文档。

以下代码会生成一个像这样的文档。

  2. class UserController extends FilterController
  3. {
  4.     public function rules()
  5.     {
  6.         return [
  7.             'get' => [
  8.                 'id' => ['required', 'integer'],
  9.                 // 'email' => ['required', 'email', ['lengthMin', 4]],
  10.             ],
  11.         ];
  12.     }
  14.     /**
  15.      * 获取用户
  16.      * @apiModule 用户
  17.      * @apiDescription 获取用户接口
  18.      * - 支持换行
  19.      * - 支持markdown
  20.      * @apiParam string id 用户ID
  21.      * @apiSuccess int code 返回码，0表示成功
  22.      * @apiSuccess string msg 提示信息
  23.      * @apiSuccess object data 提示信息
  24.      * @apiSuccess object data.user 用户
  25.      * @apiSuccess int data.user.id 用户ID
  26.      * @apiSuccess int data.user.username 用户名
  27.      * @apiSuccess int data.user.createdAt 创建时间戳
  28.      * @apiSuccessExample json 创建成果 {
  29.      *     "code":0, 
  30.      *     "message":"",
  31.      *     "data":{
  32.      *         "user": {
  33.      *             "id": 1,
  34.      *             "username": "CabalPHP",
  35.      *             "createdAt": 1530374400,
  36.      *         }
  37.      *     }
  38.      * }
  39.      * @apiError int code 错误码
  40.      * @apiError string msg 错误信息
  41.      * @apiErrorExample json Example {
  42.      *     "code": 1,
  43.      *     "message": "用户ID不存在"
  44.      * } 
  45.      * @apiErrorExample json Example2 {
  46.      *     "code": 1,
  47.      *     "message": "Id 只能是整数"
  48.      * } 
  49.      */
  50.     public function get(\Server $server, Request $request, $vars = [])
  51.     {
  52.         $id = $request->input('id');
  53.         if ($id < 10) {
  54.             return [
  55.                 'code' => 0,
  56.                 'message' => '',
  57.                 'data' => [
  58.                     'user' => [
  59.                         'id' => $request->input('id'),
  60.                         'username' => 'CabalPHP',
  61.                         'createdAt' => 1530374400,
  62.                     ],
  63.                 ],
  64.             ];
  65.         } else {
  66.             return [
  67.                 'code' => 0,
  68.                 'message' => '用户ID不存在',
  69.             ];
  70.         }
  71.     }
  72. }

支持的语法

  1.     /**
  2.      * 接口名称
  3.      * @apiDescription 接口描述 
  4.      * 可以换行支持markdown
  5.      * @apiModule 模块名称
  6.      * @apiIgnore 1
  7.      * @apiParam 字段类型 字段1 字段说明
  8.      * @apiSuccess 字段类型 字段1 字段说明
  9.      * @apiSuccess 字段类型 字段2 字段说明
  10.      * @apiError 字段类型 字段1 字段说明
  11.      * @apiError 字段类型 字段2 字段说明
  12.      * @apiSuccessExample 类型 示例名称 示例内容
  13.      * @apiErrorExample 类型 示例名称 示例内容
  14.      */