简介：apidoc是一个轻量级的在线REST接口文档生成系统，支持多种主流语言，包括Java、C、C#、PHP和Javascript等。使用者仅需要按照要求书写相关注释，就可以生成可读性好、界面美观的在线接口文档。
1、安装
apidoc是基于nodeJs平台，在安装apidoc之前，需要先安装nodeJs和npm（安装步骤省略）。
进入命令行，输入npm install apidoc -g安装
2、使用
先介绍一下apidoc中的重要命令和参数：
apidoc的命令格式如下： apidoc 参数
参数 描述 -f 选择要解析的文件，支持正则表达式。-f参数可以使用多次，多个表达式可以对应不同的-f。如：apidoc -f ".*\.js$" -f ".*\\.ts$" -i 选择源代码所在的位置。如：apidoc -i myapp/ -o 选择生成的目标文件所在的位置。如：apidoc -o apidoc/ -t 为生成文件选择模板，可以创建和使用自定义的模板。（笔者注：目前为止，笔者还没有使用过这个参数） -h 跟绝大多数命令一样，这个参数可以打印出帮助文档
以下为本地测试目录
- apidoc.json：apidoc的项目级配置文件，它必须位于整个工程目录顶层。
- Demo1.java：用于演示的demo源文件，它可以位于整个工程目录的顶层目录及其子目录下。apidoc会搜索整个工程目录选择所有可能的源文件。
apidoc.json
常用配置
配置名 描述
name 工程名。如果该字段不存在，则apidoc会尝试通过package.json（apidoc顶层配置文件）来生成
version 工程文档的版本号。如果该字段不存在，则apidoc会尝试通过package.json（apidoc顶层配置文件）来生成
description 工程详细描述。如果该字段不存在，则apidoc会尝试通过package.json（apidoc顶层配置文件）来生成
title 文档标题，显示在文档界面的最上方
url 整个api url的前缀，接下来的所有接口url都会加上这个前缀
sampleUrl api示例的url前缀。如果设置了这个值，则界面中显示请求表单，可以用于测试接口
header
title 文档头（header）的连接锚点名
filename 文档头所使用的文件
footer
title 文档尾（footer）的连接锚点名
filename 文档尾所使用的文件
order 接口的排列顺序list，如果不指定，则由apidoc自行确定
示例：
{ "name": "apidoc测试", "version": "1.0.0", "description": "这是一个简单的apidoc的demo", "title": "demo", "url" : "https://api.github.com/v1" }
Demo1.java
常用注解：
@api 定义API的请求方法、路径和名字
@apiDescription 定义API的描述
@apiGroup 定义API的分组
@apiParam 定义API的参数
@apiParamExample 参数请求的事例
@apiVersion 版本
@apiErrorExample API错误示例
@apiSuccessExample API正常示例
示例
/** * @apiGroup Product * @api {GET} /product/{id} 查询一个产品 * @apiDescription 指定产品id , 删除产品的全部信息，包括关联的schema * @apiParam {String} id 产品id(必填*) * @apiSuccessExample SuccessExample * HTTP/1.1 200 * { * id: ‘xxx‘, * modelId: ‘xxxxx‘, * name: ‘xxx‘, * intro: ‘xxxx‘ * } * @apiErrorExample ErrorExample * HTTP/1.1 600 * 具体的异常信息 */ @GetMapping("/{id}") public Product getOneProduct(@PathVariable String id) { return productServ.findOne(id); }
3、运行
进入apidoc目录，打开命令行：输入 apidoc -i src/ -o apidoc/
打开index.html就可以看到了