SpringBoot apidoc生成接口文档(附带实例)
apidoc 是一个简单的 RESTful API 文档生成工具,从代码注释中提取特定格式的内容生成文档。
apidoc 支持多种主流的编码语言,包括 Java、C、C#、PHP 和 JavaScript。一般情况下,语言会有多种注释方法,例如在 Java 中就有普通风格的多行注释和 Javadoc 风格的注释。
apidoc 并不支持所有的注释,比如 Java 中仅支持 Javadoc 风格的注释。需要说明的是,apidoc 并不具备语义识别能力,不会发现代码中是否有 BUG,仅仅通过文件后缀来判断语言类型。
它对代码没有侵入性,只需要写好相关的注释即可,并且它仅通过写简单的配置就可以生成高颜值的 api 接口页面。它是基于 Node.js 的,所以需要安装 Node.js 环境。
检查是否安装 Node.JS 命令是 npm-version,如果已安装就会输出版本号,如果没有安装则会输出错误信息“不是内部或外部命令”,需要安装 Node.js。Node.js 的下载地址为 https://node.js.org/zh-cn/,安装步骤不再赘述。
检查 apidoc 安装是否成功:
出现帮助提示则说明安装成功。
创建 IndexController 类,并创建 helloApidoc 方法、添加注释信息(使用官方注解),示例代码如下:
下面是一个配置示例:
apidoc.json 所有的配置项如下表所示。
在该示例 apidoc 注释中:
apidoc 支持多种主流的编码语言,包括 Java、C、C#、PHP 和 JavaScript。一般情况下,语言会有多种注释方法,例如在 Java 中就有普通风格的多行注释和 Javadoc 风格的注释。
apidoc 并不支持所有的注释,比如 Java 中仅支持 Javadoc 风格的注释。需要说明的是,apidoc 并不具备语义识别能力,不会发现代码中是否有 BUG,仅仅通过文件后缀来判断语言类型。
它对代码没有侵入性,只需要写好相关的注释即可,并且它仅通过写简单的配置就可以生成高颜值的 api 接口页面。它是基于 Node.js 的,所以需要安装 Node.js 环境。
检查是否安装 Node.JS 命令是 npm-version,如果已安装就会输出版本号,如果没有安装则会输出错误信息“不是内部或外部命令”,需要安装 Node.js。Node.js 的下载地址为 https://node.js.org/zh-cn/,安装步骤不再赘述。
安装apidoc
使用 npm 命令进行安装:npm install apidoc -g
检查 apidoc 安装是否成功:
apidoc -h
出现帮助提示则说明安装成功。
Spring Boot中使用apidoc生成接口文档
首先创建一个空的 Spring Boot 项目,项目名为 apidoc-demo。在项目根路径下创建 apidoc.json 文件,内容如下所示:{ "name": "测试api文档", "version": "0.1.0", "description": "这只是一个测试的页面", "title": "APIDOC测试", "url" : "http://localhost:8080", "sampleUrl": "http://localhost:8080" }
创建 IndexController 类,并创建 helloApidoc 方法、添加注释信息(使用官方注解),示例代码如下:
import ... /** * 接口文档测试首页 */ @RestController public class IndexController { /** * @api {get} /hello-apidoc 测试 * @apiName hello-apidoc * @apiDescription api 接口文档测试 * @apiGroup index * @apiSampleRequest /hello-apidoc */ @GetMapping("/hello-apidoc") public String helloApidoc() { return "Hello Apidoc"; } /** * @api {get} /memberlist 会员列表 * @apiDescription 会员用户列表展示 * @apiName memberlist * @apiParam {String} type 会员类型 * @apiParamExample {json} Request-Example: * { * "type":"svip" * } * @apiGroup index * @apiSampleRequest /memberlist */ @PostMapping("/memberlist") public List<String> memberList(String type) { List<String> list = new ArrayList<>(); list.add("小明"); list.add("小李"); list.add("小红"); return list; } }最后生成接口文档,需要在控制台进入项目的外面一层目录,例如本示例项目路径为 D:\code\idea\apidoc-demo,就需要在 D:\code\idea 目录下执行以下命令生成接口文档:
apidoc -i apidoc-demo/ -o apidoc-demo-doc/其中,-i 参数表示输入的路径,-o 参数表示输出路径。执行完成后,生成的接口文档在 apidoc-demo-doc 目录下,在浏览器中打开 index.html 页面,就可以看到如下图所示的接口文档信息。

apidoc.json配置详解
apidoc.json 放置在项目根目录中,可选内容包括有关项目的常用信息,例如标题、简短描述、版本和配置选项(例如页眉/页脚设置或模板特定的选项)。下面是一个配置示例:
{ "name": "example", "version": "0.1.0", "description": "apiDoc basic example", "title": "Custom apiDoc browser title", "url" : "https://api.github.com/v1" }
apidoc.json 所有的配置项如下表所示。
配置项 | 说明 |
---|---|
name | 项目名称 |
version | 项目版本号 |
description | 项目简介 |
title | apidoc 在浏览器中显示的标题 |
url | 接口地址的前缀,比如 https://api.github.com/v1 |
useHostUrlAsSampleUrl | 如果设置为 true,那么主机URL 地址将使用 sampleUrl 配置的地址,默认为 false |
sampleUrl | 如果设置此地址,那么将会展示一个测试请求该 api 的表单,详细介绍请看 @apiSampleRequest 注解 |
header.title | 设置页眉标题 |
header.filename | 页眉文件的文件名(markdown 文件) |
footer.title | 页脚文本 |
footer.filename | 页脚文件的文件名(markdown 文件) |
order |
用于排序输出的 api 名称/组名称的列表,未定义的名称将自动显示在最后。 示例:"order": ["Error","Define","PostTitleAndError","PostError"] |
apidoc命令详解
使用命令“apidoc -h”可以查看所有支持的命令和参数。重要的参数说明如下表所示。参数 | 描述 |
---|---|
-f, --file-filters |
RegEx-Filter 选择要分析的文件(可多次使用 -f)。 默认:.cs .dart .erl .go .java .js .php .py .rb .ts 示例(仅解析 .js 和 .ts 文件): apidoc -f ".*\.js$" -f ".*\.ts$" |
-i, --input |
输入 / 源目录名,项目文件的位置。 示例:apidoc -i myapp/ |
-o, --output |
输出目录名,放置生成的文档的位置。 示例:apidoc -o apidoc/ |
-t, --template |
使用模板输出文件,可创建并使用自己的模板。 示例:apidoc -t mytemplate/ |
-e, --exclude-filters |
RegEx-Filter 选择不应解析的文件 / 目录(可多次使用 -e)。 默认值:[] 示例:apidoc -e node_modules |
apidoc注释详解
一个比较完整的 apidoc 注释示例如下面的代码所示:/** * @api {get} /user/:id Request User information * @apiName GetUser * @apiGroup User * * @apiParam {Number} id User's unique ID. * * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. * * @apiSuccessExample {json} Success-Response: * HTTP/1.1 200 OK * { * "firstname": "John", * "lastname": "Doe" * } * * @apiError UserNotFound The id of the User was not found. * * @apiErrorExample {json} Error-Response: * HTTP/1.1 404 Not Found * { * "error": "UserNotFound" * } */apidoc 文档块以 /** 开头、以 */ 结尾。本示例描述了一种通过获取请求方式来获取来用户信息的方法。
在该示例 apidoc 注释中:
- @api {get} /user/:id Request User information 是强制性的,没有 @apiapiDoc 会忽略文档块;
- @apiName )必须是唯一名称,并且应始终使用,格式为“方法+路径(例如,获取+用户)”;
- @apiGroup 应该始终使用,并用于将相关的 API 组合在一起;
- 其他字段都是可选的,具体说明可以参考官方文档(https://apidocjs.com/#params)。
相关文章
- SpringBoot是什么?SpringBoot的优缺点有哪些?
- SpringBoot URL映射详解(附带实例)
- SpringBoot @PathVariable实现参数传递(附带实例)
- SpringBoot传递参数的5种方法(附带实例)
- SpringBoot @Scheduled定时任务详解(附带实例)
- SpringBoot Cron表达式的用法(新手必看)
- SpringBoot @Scheduled实现定时任务(附带实例)
- SpringBoot集成Redis详解(附带实例)
- SpringBoot集成RabbitMQ详解(附带实例)
- SpringBoot实现RabbitMQ简单队列(附带实例)