1.什么是Apidoc
Apidoc是一款可以由源代码中的注释直接自动生成api接口文档的工具，它几乎支持目前主流的所有风格的注释。可以在C#, Go, Dart, Java, JavaScript, PHP, TypeScript等语言中使用
2.友好的文档展示页面
3.注释生成接口文档的原理
apidoc的原理是扫描你的代码文件，提取出注释部分，根据一些规则生成相应的文档。默认的模板久简洁美观，十分适合作为api文档的生成器。
4.Apidoc安装
环境：需要使用npm安装，如果没有安装npm，请先去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 => 接口的描述
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()
{...}
看结果>>>>>
Tips:
①apidoc注释一般书写位置：控制器，即对外的接口，接受参数和返回响应的接口 ②和其它注释不会冲突，一般先写apidoc注释，再写其它注释，其它注释信息不会展示在apidoc文档中 ③可以直接在注释中放json，通过@apiSuccessExample {json}参数，显示更直接 ④如果参数和返回值中存在层级关系，则参考对象的方式，用"."连接，示例： person.age
8.Apidoc使用过程中的坑
这个也不算是坑，只是存在这个误区，@apiGroup参数是不能写中文的，即使写了中文，它显示的时候不会解析，网上有的小伙伴给出的解决办法是去修改Apidoc的源码，让它解析，但这种方式有点刻舟求剑，你自己修改了，能显示中文，但是你的团队什么都看不到，除非他们每个人都修改。在此给出正确显示中文的方式。通过@apiDefine参数，定义一个宏变量，类似于定义常量
在接口的file里，添加过@apiDefine参数，这样这个file都可以使用这个参数
/**
* @apiDefine employee 员工信息
*/
使用方式：像使用常量的方式，把常量放在@apiGroup后即可，这样group就能正确显示中文了
@apiGroup soa_employee
9.Apidoc官方文档
Apidoc文档是英文的，描述得很清楚
