FastAdmin命令行一键生成API文档

作者 : 小优 本文共3462个字,预计阅读时间需要9分钟 发布时间: 2021-04-28 共75人阅读
 一键生成API文档 FastAdmin中的一键生成API文档可以在命令行或后台一键生成我们API接口的接口测试文档,可以直接在线模拟接口请求,查看参数示例和返回示例。准备工作 请确保你的API模块下的控制器代码没有语法错误,控制器类注释、方法名注释完整,注释规则请参考下方注释规则 请确保你的FastAdmin已经安装成功且能正常登录后台 请确保php所在的目录已经加入到系统环境变量,否则会提示找不到该命令 打开命令行控制台进入到FastAdmin根目录,也就是think文件所在的目录

一键生成API文档

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

准备工作

请确保你的API模块下的控制器代码没有语法错误,控制器类注释、方法名注释完整,注释规则请参考下方注释规则
请确保你的FastAdmin已经安装成功且能正常登录后台
请确保php所在的目录已经加入到系统环境变量,否则会提示找不到该命令
打开命令行控制台进入到FastAdmin根目录,也就是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
//修改标题为FastAdmin,作者为作者
php think api -t FastAdmin -a Karson --force=true
//查看API接口命令行帮助
php think api -h

参数介绍

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

注释规则

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

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

控制器方法注释

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

标准范例

<?php
 
namespace appapicontroller;
 
/**
 * 测试API控制器
 */
class Test extends appcommoncontrollerApi
{
 
    // 无需验证登录的方法
    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());
    }
 
}

常见问题

如果控制器的方法是private或protected的,则将不会生成相应的API文档
如果注释不生效,请检查注释文本是否正确

资源下载说明

请使用百度网盘下载资源,请不要在线解压!

1.人民币与U币汇率为1比10,即1元=10U币.有任何疑问请联系客服处理!
2.请记住本站永久网址发布页:http://uuscw.com
3.本站资源大多存储在云盘,如发现链接失效请在下方评论留言,作者看到后会第一时间更新补链。
4.关于解压密码错误或者资源损坏,请查看解压教程:[必看]关于资源教程及常见问题
5.本站大部分资源解压密码均为: uuscw.com 如密码有误,请查看原帖的资源说明!

免责申明:
1.如果服务器暂不能下载请稍后重试!总是不能下载,请联系客服,谢谢合作!
2.本站所有资源(包括写真、模板、素材、软件、字体等)仅供学习与参考,请勿用于商业用途。
3.本站所有素材来源于用户上传和网络,如有侵权请请联系客服处理!
4.本站资源售价只是赞助,收取费用仅维持本站的日常运营所需。
UU素材网 » FastAdmin命令行一键生成API文档

常见问题FAQ

免费下载或者VIP会员专享资源能否直接商用?
本站所有资源版权均属于原作者所有,这里所提供资源均只能用于参考学习用,请勿直接商用。若由于商用引起版权纠纷,一切责任均由使用者承担。更多说明请参考 VIP介绍。
提示下载完但解压或打开不了?
最常见的情况是下载不完整: 可对比下载完压缩包的与网盘上的容量,若小于网盘提示的容量则是这个原因。这是浏览器下载的bug,建议用百度网盘软件或迅雷下载。 若排除这种情况,可在对应资源底部留言,或 联络我们。

发表评论