Spring Boot整合JApiDocs实现API文档

对Swagger相当不爽的两点，一是要大量写各种注解，二是很被诟病的一点，对返回对象的描述相当不人性化（虽然可以写代码来实现，但不爽）。

在大部分时候，我们其实只关注接口的4个方面： 接口功能描述、接口URL、提交参数说明、返回结果说明。
JApiDocs完美的满足上面的基本要求，见下图：

 

接口文档生成器——JApiDocs

下面的步骤是大量照搬JApiDocs官网的内容。

第一步：添加依赖
通过IDEA创建Spring Boot，在创建工程时，可以把web依赖勾选上（不勾选也没关系，后面在pom.xml中再添加也行）。

<dependency>
<groupId>io.github.yedaxia</groupId>
<artifactId>japidocs</artifactId>
<version>1.4.4</version>
</dependency>

第二步：配置参数
在任意一个main入口运行下面的代码，我是直接写在Spring Boot的启动类中的，如下：

 DocsConfig config = new DocsConfig();
            // 获取项目路径
            try {
    			Properties props=System.getProperties(); //获得系统属性集
    			String userDir=props.getProperty("user.dir");	// 用户的当前工作目录
    			config.setProjectPath(userDir); // 项目根目录
    			config.setProjectName("jwbasta-thymeleaf"); // 项目名称
    			config.setApiVersion("V1.0"); // 声明该API的版本
    			config.setDocsPath(userDir+"/src/main/resources/static/apidoc"); // 生成API 文档所在目录
    			config.setAutoGenerate(Boolean.TRUE); // 配置自动生成
    			Docs.buildHtmlDocs(config); // 执行生成文档
    		} catch (Exception e) {
    			logger.error("生成API文档异常:"+e.getMessage(), e);
    		}

在编码时，你只需注意编码规范，，顺手写好必要的注释就行了，那么接口文档就能自动生成，不用加任何注解。

1. 类上加注释（不是注解）
“广告管理接口”注释会显示为左侧树形目录的根目录

/**
 * 广告管理接口
 * @author jiangwei
 *
 */
@Controller
@RequestMapping("/api/ad")
public class ApiAdController extends BaseController{
	
   ....

  
}

2. 方法上加注释（不是注解）
"新增广告接口"会显示为左侧导航树的目录，@description会显示为副标题，每一个参数对应一个@param

/**
     * 新增保存广告
     * 
     * @description 新增广告需要传广告标题等参数
     * @param adVo 广告实体
     * 
     */
    @SaCheckPermission("sys:ad:add")
    @PostMapping("/save")
    @ResponseBody
    public JSONObject addSave(WebAdVo adVo){
    	adService.insertWebAdVo(adVo);
        return success();
    }

3. 实体类上加注释（不是注解）
直接在属性上面加注释就行了，用//或者*注释都行，我比较喜欢用//，见下图：

 

备注：

JApiDocs生成文档项目发布前提前生成好，jar包和class文件不能生成html文档