Apidoc的安装配置及使用

1.什么是Apidoc

Apidoc是一款可以由源代码中的注释直接自动生成api接口文档的工具，它几乎支持目前主流的所有风格的注释。可以在C#, Go, Dart, Java, JavaScript, PHP, TypeScript等语言中使用

2.友好的文档展示页面

example.png

3.注释生成接口文档的原理

apidoc的原理是扫描你的代码文件，提取出注释部分，根据一些规则生成相应的文档。默认的模板久简洁美观，十分适合作为api文档的生成器。

4.Apidoc安装

环境：需要使用npm安装，如果没有安装npm，请先去https://www.npmjs.com/下载npm并且安装。npm官网需要注册账号，另一种方式是安装node，会自动安装npm工具安装node教程

①安装：

npm install apidoc -g

②验证安装是否成功：

apidoc -h          出现帮助信息则安装成功

③配置apidoc.json文件

在项目的根目录建立apidoc.json文件

{
  "name": "appleFarm",                  //文档项目名
  "title": "appleFarmAPI",              //html标题
  "description":"API接口文档",           //文档描述
  "url" : "https://www.google.com",     //公共接口地址
  "version": "0.1.0"                    //文档版本
}

5.Apidoc使用

apidoc -i /src  -o public/static       生成文档的命令

/src ：生成接口文档的源文件
public/static ：生成的接口文档地址（一般放在静态文件夹下）

6.常用Apidoc注释规则举例

@api {post} add_team 新建球队 => {请求方式} 路由接口名称
@apiGroup team => 分组的名称，方便管理分组
@apiParam {String} name 名字. => {参数类型} [参数名] 参数描述
@apiSuccess {String} msg 详细信息. => {响应的类型} 参数响应描述
@apiSuccessExample Success-Response: => 成功返回的示例，可返json
@apiErrorExample {json} Error-Response: => 失败返回的示例，可返json
@apiDescription This is the Description => 接口的描述
1.官方手册
 2.中文说明

7.Apidoc示例及Tips

上代码 >>>>>

    /**
     * @api {post} /admin_login  用户登录
     * @apiGroup  admin
     * @apiParam {Number}   account     账号（手机号）.
     * @apiParam {String}   pw  密码.
     * @apiSuccess {String} msg 详细信息.
     * @apiSuccess {Number} status 状态码（1：登录成功，2：密码或账号错误，3：参数验证失败）
     * @apiSuccess {Number} is_admin （身份标识：-1普通注册，0球员，1及以上，代表创建的球队个数）.
     * @apiSuccessExample {json} Success-Response:
     * {
     * "msg": "登录成功",
     * "status": 1,
     * "data": {
     * "user_id": 4,
     * "is_admin": 2
     * }
     * }
     * @return \think\response\Json
     * @throws \think\db\exception\DataNotFoundException
     * @throws \think\db\exception\ModelNotFoundException
     * @throws \think\exception\DbException
     */
    public function login() 
    {...}

看结果>>>>>

apidoc.png

Tips:
①apidoc注释一般书写位置：控制器，即对外的接口，接受参数和返回响应的接口
②和其它注释不会冲突，一般先写apidoc注释，再写其它注释，其它注释信息不会展示在apidoc文档中
③可以直接在注释中放json，通过@apiSuccessExample {json}参数，显示更直接
④如果参数和返回值中存在层级关系，则参考对象的方式，用"."连接，示例： person.age

最后编辑于：2019.05.31 18:18:09