首页 > 编程笔记 > Java笔记 阅读：21

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

使用 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 所有的配置项如下表所示。

表：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”可以查看所有支持的命令和参数。重要的参数说明如下表所示。

表：apidoc命令的重要参数及其说明
参数 描述
-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 注释中：

相关文章