一键生成API文档

FastAdmin中的一键生成API文档可以在命令行或后台一键生成我们API接口的接口测试文档，可以直接在线模拟接口请求，查看参数示例和返回示例。

准备工作

请确保你的API模块下的控制器代码没有语法错误，控制器类注释、方法名注释完整，注释规则请参考下方注释规则

请确保你的FastAdmin已经安装成功且能正常登录后台

请确保php所在的目录已经加入到系统环境变量，否则会提示找不到该命令

打开命令行控制台进入到FastAdmin根目录，也就是think文件所在的目录

常用命令

  1. //一键生成API文档
  2. php think api --force=true
  3. //指定https://www.example.com为API接口请求域名,默认为空
  4. php think api -u https://www.example.com --force=true
  5. //输出自定义文件为myapi.html,默认为api.html
  6. php think api -o myapi.html --force=true
  7. //修改API模板为mytemplate.html，默认为index.html
  8. php think api -e mytemplate.html --force=true
  9. //修改标题为FastAdmin,作者为作者
  10. php think api -t FastAdmin -a Karson --force=true
  11. //查看API接口命令行帮助
  12. php think api -h

参数介绍

  1. -u, --url[=URL]            默认API请求URL地址 [default: ""]
  2. -m, --module[=MODULE]      模块名(admin/index/api) [default: "api"]
  3. -o, --output[=OUTPUT]      输出文件 [default: "api.html"]
  4. -e, --template[=TEMPLATE]  模板文件 [default: "index.html"]
  5. -f, --force[=FORCE]        覆盖模式 [default: false]
  6. -t, --title[=TITLE]        文档标题 [default: "FastAdmin"]
  7. -a, --author[=AUTHOR]      文档作者 [default: "FastAdmin"]
  8. -c, --class[=CLASS]        扩展类 (multiple values allowed)
  9. -l, --language[=LANGUAGE]  语言 [default: "zh-cn"]

注释规则

在我们的控制器中通常分为两部分注释，一是控制器头部的注释，二是控制器方法的注释。

控制器注释

名称描述示例
@ApiSectorAPI分组名称(测试分组)
@ApiRouteAPI接口URL，此@ApiRoute只是基础URL(/api/test)
@ApiInternal忽略的控制器,表示此控制将不加入API文档无
@ApiWeighAPI方法的排序,值越大越靠前(99)

控制器方法注释

名称描述示例
@ApiTitleAPI接口的标题,为空时将自动匹配注释的文本信息(测试标题)
@ApiSummaryAPI接口描述(测试描述)
@ApiRouteAPI接口地址,为空时将自动计算请求地址(/api/test/index)
@ApiMethodAPI接口请求方法,默认为GET(POST)
@ApiSectorAPI分组,默认按钮控制器或控制器的@ApiSector进行分组(测试分组)
@ApiParamsAPI请求参数,如果在@ApiRoute中有对应的{@参数名}，将进行替换(name="id", type="integer", required=true, description="会员ID")
@ApiHeadersAPI请求传递的Headers信息(name=token, type=string, required=true, description="请求的Token")
@ApiReturnAPI返回的结果示例({"code":1,"msg":"返回成功"})
@ApiReturnParamsAPI返回的结果参数介绍(name="code", type="integer", required=true, sample="0")
@ApiReturnHeadersAPI返回的Headers信息(name="token", type="integer", required=true, sample="123456")
@ApiInternal忽略的方法,表示此方法将不加入文档无
@ApiWeighAPI方法的排序,值越大越靠前(99)

标准范例

  1. <?php
  3. namespace app\api\controller;
  5. /**
  6.  * 测试API控制器
  7.  */
  8. class Test extends \app\common\controller\Api
  9. {
  11.     // 无需验证登录的方法
  12.     protected $noNeedLogin = ['test'];
  13.     // 无需要判断权限规则的方法
  14.     protected $noNeedRight = ['*'];
  16.     /**
  17.      * 首页
  18.      *
  19.      * 可以通过@ApiInternal忽略请求的方法
  20.      * @ApiInternal
  21.      */
  22.     public function index()
  23.     {
  24.         return 'index';
  25.     }
  27.     /**
  28.      * 私有方法
  29.      * 私有的方法将不会出现在文档列表
  30.      */
  31.     private function privatetest()
  32.     {
  33.         return 'private';
  34.     }
  36.     /**
  37.      * 测试方法
  38.      *
  39.      * @ApiTitle    (测试名称)
  40.      * @ApiSummary  (测试描述信息)
  41.      * @ApiSector   (测试分组)
  42.      * @ApiMethod   (POST)
  43.      * @ApiRoute    (/api/test/test/id/{id}/name/{name})
  44.      * @ApiHeaders  (name=token, type=string, required=true, description="请求的Token")
  45.      * @ApiParams   (name="id", type="integer", required=true, description="会员ID")
  46.      * @ApiParams   (name="name", type="string", required=true, description="用户名")
  47.      * @ApiParams   (name="data", type="object", sample="{'user_id':'int','user_name':'string','profile':{'email':'string','age':'integer'}}", description="扩展数据")
  48.      * @ApiReturnParams   (name="code", type="integer", required=true, sample="0")
  49.      * @ApiReturnParams   (name="msg", type="string", required=true, sample="返回成功")
  50.      * @ApiReturnParams   (name="data", type="object", sample="{'user_id':'int','user_name':'string','profile':{'email':'string','age':'integer'}}", description="扩展数据返回")
  51.      * @ApiReturn   ({
  52.         'code':'1',
  53.         'mesg':'返回成功'
  54.      * })
  55.      */
  56.     public function test($id = '', $name = '')
  57.     {
  58.         $this->success("返回成功", $this->request->request());
  59.     }
  61. }

常见问题

如果控制器的方法是private或protected的，则将不会生成相应的API文档

如果注释不生效，请检查注释文本是否正确