Spring Boot（七）之apidoc生成

灰太狼 2022-05-16 09:07 247阅读 0赞

### Spring Boot（七）之apidoc生成 ###

#### 1.安装apidoc ####

在安装apidoc之前需要安装node.js，下面介绍下Mac OS安装

1.1 安装node.js

前往 [https://nodejs.org/en/][https_nodejs.org_en] 下载node.js的最新版本，双击.pkg进行安装

一路安装即可，安装完成后，在终端输入`node -v`，`npm -v`。出现对应的版本号表示安装成功。

![image][]

1.2 使用npm安装apidoc

在终端输入 `npm install apidoc –g`

前往 [https://github.com/apidoc/apidoc/][https_github.com_apidoc_apidoc] 下载apidoc 的demo

在终端进入刚下载的demo路径

在终端输入apidoc -i example/ -o doc/，如显示info: Done.即apidoc环境搭建成功

![image][image 1]

#### 2.编写apidoc文档 ####

在Controller中的方法上面编写apidoc文档，内容如下：

package com.zhang.springbootmybatisdemo.controller;
    
    import com.zhang.springbootmybatisdemo.domain.User;
    import com.zhang.springbootmybatisdemo.service.UserService;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.*;
    
    import java.util.List;
    
    /** * @apiDefine spring boot demo * spring boot demo 接口 */
    @RestController
    @RequestMapping("/user")
    public class UserController { 
    
        @Autowired
        private UserService userService;
    
        /** * @api {post} /user/add 添加User的接口 * @apiName 添加用户 * @apiGroup user * @apiDescription 添加用户的接口 * @apiParam userId 用户id * @apiParam username 用户名 * @apiParam password 用户名密码 * @apiParamExample {json} * Request-Example 1: * { * "userId":"1001", * "username":"caocao", * "password":"123456" * } * @apiSuccess 1 */
        @PostMapping("/add")
        public int add(@RequestBody User user) {
            return userService.addUser(user);
        }
    
        /** * @api {post} /user/search 查询用户的接口 * @apiName 通过id查询用户 * @apiGroup user * @apiDescription 通过id查询用户的接口 * @apiParam userId 用户id * @apiParamExample {json} * Request-Example 1: * {"userId":"1001"} * @apiSuccess {String} userId 用户id * @apiSuccess {String} username 用户名 * @apiSuccess {String} password 用户名密码 * @apiSuccessExample {json} Success-Response: * { * "userId": "1001", * "username": "caocoa", * "password":"123456" * } */
        @ResponseBody
        @PostMapping("/search")
        public User searchById(@RequestBody User user) {
            return userService.searchById(user.getUserId());
        }
    
    
        /** * @api {post} /user/searchall 查询所有用户的接口 * @apiName 查询所有用户 * @apiGroup user * @apiDescription 查询所有用户的接口 * @apiSuccess {String} userId 用户id * @apiSuccess {String} username 用户名 * @apiSuccess {String} password 用户名密码 * @apiSuccessExample {json} Success-Response: * [ * { * "userId": "1001", * "username": "caocao", * "password": "123456" * }, * { * "userId": "1002", * "username": "liubei", * "password": "123456" * } * ] */
        @ResponseBody
        @PostMapping("/searchall")
        public List<User> searchAll() {
            return userService.searchAll();
        }
    }

#### 3.apidoc配置 ####

dev目录下的apidoc.json

{
      "name": "Spring Boot Demo Api",
      "version": "1.0.0",
      "title": "BIGDATA-API",
      "url": "http://localhost:8080",
      "sampleUrl": "http://localhost:8080",
      "template": { "forceLanguage": "zh-cn" },
      "template": { "withCompare": true, "withGenerator": true },
      "template": { "jQueryAjaxSetup": { "contentType": "application/json" } } }

这里dev，test，prod配置成一样的，都是localhost:8080

![image][image 2]

#### 4.apidoc执行命令 ####

编写apidoc的执行脚本

**`apidoc.sh`**

#!/usr/bin/env bash 
    workspace=$(pwd)
    appName=$(basename ${workspace})
    env=$1
    
    logDir=${workspace}/log
    targetDir=${workspace}/target
    
    echo "<<<<<<<<<<<<<<<<<<<<<<<<"
    echo "build apidoc ..."
    echo ">>>>>>>>>>>>>>>>>>>>>>>>"
    
    apiTemplateDir=${workspace}/apidoc/${env}
    apiName=${appName/%-demo/-doc}
    
    
    apidoc -i ${workspace}/src/main/java/com/zhang/springbootmybatisdemo/controller -o ${targetDir}/${apiName} -c ${apiTemplateDir}

![image][image 3]

查看apidoc的内容：

![image][image 4]

在浏览器打开index.html

![image][image 5]

![image][image 6]

![image][image 7]

这里只是截取了apidoc接口的部分

[https_nodejs.org_en]: https://nodejs.org/en/
[image]: https://raw.githubusercontent.com/zhang3550545/image_center/master/image-2018/spring-boot-apidoc-01.png
[https_github.com_apidoc_apidoc]: https://github.com/apidoc/apidoc/
[image 1]: /images/20220516/28f201ed13054b7ca0a0e2e81e048c89.png
[image 2]: /images/20220516/a020219d1cea4a77859d58cf18e87d81.png
[image 3]: /images/20220516/6446745effd9402fb771635510481317.png
[image 4]: /images/20220516/a5f6d539b8e541e1ae88a535203b865e.png
[image 5]: /images/20220516/be2c9cec64594f998d9d07213960d6ef.png
[image 6]: /images/20220516/2ee095931fb14b96b2cba836b8b39b1b.png
[image 7]: /images/20220516/9f483a19e1cb4581bd8d6649e4454f91.png