一键生成API文档

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

准备工作

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

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

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

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

常用命令

//一键生成API文档
php think api --force=true
//指定https://www.example.com为API接口请求域名,默认为空
php think api -u https://www.example.com --force=true
//输出自定义文件为myapi.html,默认为api.html
php think api -o myapi.html --force=true
//修改API模板为mytemplate.html，默认为index.html
php think api -e mytemplate.html --force=true
//生成指定控制器Demo的API文档
php think api -r Demo --force=true
//修改标题为Demo,作者为Lily
php think api -t Demo -a Lily --force=true
//生成插件标识为cms的API文档
php think api -a cms -o cmsapi.html --force=true
//查看API接口命令行帮助
php think api -h

参数介绍

-u, --url[=URL]            默认API请求URL地址 [default: ""]
-m, --module[=MODULE]      模块名(admin/index/api) [default: "api"]
-a, --addon[=ADDON]      插件标识(addons目录下的插件标识) [default: ""]
-o, --output[=OUTPUT]      输出文件 [default: "api.html"]
-e, --template[=TEMPLATE]  模板文件 [default: "index.html"]
-f, --force[=FORCE]        覆盖模式 [default: false]
-t, --title[=TITLE]        文档标题 [default: "FastAdmin"]
-c, --class[=CLASS]        扩展类 (支持多个值)
-l, --language[=LANGUAGE]  语言 [default: "zh-cn"]
-r,  --controller=CONTROLLER  控制器，默认为controller目录下的所有控制器(支持多个值),FastAdmin 1.3.0+支持

注释规则

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

控制器注释

控制器方法注释

标准范例

<?php

namespace app\api\controller;

/**
 * 测试API控制器
 */
class Test extends \app\common\controller\Api
{

    // 无需验证登录的方法
    protected $noNeedLogin = ['test'];
    // 无需要判断权限规则的方法
    protected $noNeedRight = ['*'];

    /**
     * 首页
     *
     * 可以通过@ApiInternal忽略请求的方法
     * @ApiInternal
     */
    public function index()
    {
        return 'index';
    }

    /**
     * 私有方法
     * 私有的方法将不会出现在文档列表
     */
    private function privatetest()
    {
        return 'private';
    }

    /**
     * 测试方法
     *
     * @ApiTitle    (测试名称)
     * @ApiSummary  (测试描述信息)
     * @ApiSector   (测试分组)
     * @ApiMethod   (POST)
     * @ApiRoute    (/api/test/test/id/{id}/name/{name})
     * @ApiHeaders  (name=token, type=string, required=true, description="请求的Token")
     * @ApiParams   (name="id", type="integer", required=true, description="会员ID")
     * @ApiParams   (name="name", type="string", required=true, description="用户名")
     * @ApiParams   (name="data", type="object", sample="{'user_id':'int','user_name':'string','profile':{'email':'string','age':'integer'}}", description="扩展数据")
     * @ApiReturnParams   (name="code", type="integer", required=true, sample="0")
     * @ApiReturnParams   (name="msg", type="string", required=true, sample="返回成功")
     * @ApiReturnParams   (name="data", type="object", sample="{'user_id':'int','user_name':'string','profile':{'email':'string','age':'integer'}}", description="扩展数据返回")
     * @ApiReturn   ({
        'code':'1',
        'mesg':'返回成功'
     * })
     */
    public function test($id = '', $name = '')
    {
        $this->success("返回成功", $this->request->request());
    }

}

文档模板

如果需要修改生成API文档的模板，可以自行对模板文件：application/admin/command/Api/template/index.html 进行二次开发。

常见问题

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

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