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
网友评论