Spring Boot（七）之apidoc生成

Spring Boot（七）之apidoc生成

1.安装apidoc

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

1.1 安装node.js

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

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

1.2 使用npm安装apidoc

在终端输入 npm install apidoc –g

前往 https://github.com/apidoc/apidoc/ 下载apidoc 的demo

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

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

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

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}

查看apidoc的内容：

在浏览器打开index.html

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