Springboot中使用apidoc生成接口文档

为什么需要接口文档

1. 当前后端分离时，需要前后端共同定义接口，编写接口文档。所以，在项目开发过程中需要有一个统一的文件进行沟通交流开发。
2. 对开发人员而言，项目的维护和人员更迭，都需要文档来作为记录。方便后期人员查看、维护。

有哪些常用的API自动生成文档工具

1. swagger 这款工具感觉是最常用的一款自动生成文档的工具。
   附上官网地址：https://swagger.io/
2. apidoc。第一次见到这个api文档是在公司的cmdb的接口文档中看见，个人比较喜欢这种风格的。
   附上github地址：https://github.com/apidoc/apidoc

一些准备工作

1. 确认当前电脑安装了node.js。检测是否安装

   node -h
   

   出现提示，表明已经安装node.js。如果没有，需要安装node.js

2. 安装apidoc

   npm install apidoc -g
   

   然后再测试一下apidoc是否安装成功

   apidoc -h
   

springboot中使用apidoc

首先准备一个空的springboot的项目。

新建package.json 文件

位置如下图所示：

package.json 文件内容：

{
  "name": "测试api文档",
  "version": "0.1.0",
  "description": "这只是一个测试的页面",
  "title": "APIDOC 测试",
  "url" : "https://127.0.0.1:8080/",
  "sampleUrl":"https://127.0.0.1:8080/"
}

我感觉解释一下都很抽象，还不如贴个图划算。
这边需要注意的是sampleUrl参数。在使用@apiSampleRequest注解时（在线模拟接口请求），请求地址url会自动使用package.json中的sampleUrl参数做为前缀。

方法加上注释：

	 /**
     * @api {get} /index/:userName
     * @apiDescription  这只是一个测试的接口描述
     * @apiName index
     * @apiParam {String} userName 用户的姓名
     * @apiParam {Number} userAge 用户的年龄
     * @apiParamExample {json} Request-Example:
     * {
     *     "userName":"caojing",
     *     "userAge":12
     * }
     * @apiGroup index
     * @apiError userNotFound  The id
     * @apiSampleRequest /index
     */
    @RequestMapping("/index")
    @ResponseBody
    @CrossOrigin
    public String index(@RequestParam("userName") String userName, @RequestParam("userAge") int userAge) {
        return "index userName is " + userName + "userAge " + userAge;
    }

很简单，直接在方法上面加入注释，在注释中使用官方的一些注解来解释方法的属性。

生成文档

apidoc 和 swagger不同的是，接口文档和代码文件都是分开的。一开始只需要专心编写接口代码，当代码编写完成时，只需在方法上加上指定的注释。（到这里，也就是我上述所描述的内容）。最终通过一段命令执行生成最终的html文档。
回归正题，在准备工作中我们已经安装了apidoc，然后我们通过apidoc命令生成文档：

apidoc -i apiTestDemo/ -o apidocDemo/

结果：

-i 指定源文件的目录，也就是项目的根目录。
-o 指定输出 文档的目录，生成文档的地址。
页面展示：
打开index 页面：

ok，到这里再对照前面的package.json 中的内容看，就已经很明了了。

遇到的问题

1. apidoc 不是内部或外部命令，也不是可运行程序。
   解决方案：这种问题首先排除没有安装apidoc的可能性，如果安装了apidoc，也就是在当前目录下不能使用apidoc这个命令，那么我们改在什么目录下使用呢，其实在安装apidoc 我们注意一下输出内容：
   
   将cmd切换到对应的目录下（我的是 D:\nodejs\npmInstall），在当前目录下执行apidoc 就可以了。
2. 使用@apiSampleRequest在线调试的时候，报错：
   
   这个问题可能有2个原因：
   1 地址有问题。解决方案：将URL地址写全。
   2 跨域访问问题：解决方案：在方法上面加入注解：@CrossOrigin