SpringBoot集成JApiDocs实现自动生成接口文档

 

一、概念

JApiDocs 是一个符合 Java 编程习惯的 Api 文档生成工具。最大程度地利用 Java 的语法特性，你只管用心设计好接口，添加必要的注释，JApiDocs 会帮你导出一份漂亮的 Html 文档，并生成相关的 Java 和 Object-C 相关数据模型代码，从此，Android 和 IOS 的同学可以少敲很多代码了，你也不需要费力维护接口文档的变化，只需要维护好你的代码就可以了。

二、特性

1. 以一个 Controller 作为一组接口导出到一个 Html 文件中。
2. 支持生成 Java 和 Object-C 语言的 Response 模型代码。
3. 深度支持 Spring Boot， PlayFramework，JFinal，不需要额外声明路由。
4. 支持一般的 Java Web 工程，需要在相关方法添加额外的路由。
5. 支持接口声明过时(@Deprecated)，方便的文档目录等。
6. 支持自定义代码生成模板。
7. 支持集成发布到 RAP。
8. :new: 支持多模块、泛型。

三、搭建

参考网址: https://japidocs.agilestudio.cn/#/zh-cn/

第一步：添加依赖

maven:

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

gradle:

compile 'io.github.yedaxia:japidocs:1.4.2'

第二步：配置参数

你可以在任意一个main入口运行下面的代码：

DocsConfig config = new DocsConfig();
config.setProjectPath("your springboot project path"); // 项目根目录
config.setProjectName("ProjectName"); // 项目名称
config.setApiVersion("V1.0");       // 声明该API的版本
config.setDocsPath("your api docs path"); // 生成API 文档所在目录
config.setAutoGenerate(Boolean.TRUE);  // 配置自动生成
Docs.buildHtmlDocs(config); // 执行生成文档

我的配置

package com.kero99.utils;
import io.github.yedaxia.apidocs.Docs;
import io.github.yedaxia.apidocs.DocsConfig;
/**
 * 接口文档自动生成工具
 * @author ygc
 *
 */
public class DocUtil {
		public static void main(String[] args) {
			DocsConfig config = new DocsConfig();
			// 项目根目录
			config.setProjectPath("D:\\java\\Eclipse项目\\20200817_V1.0_soilgis"); 
			// 项目名称
			config.setProjectName("20200817_V1.0_soilgis"); 
			// 声明该API的版本
			config.setApiVersion("20200817_V1.0_soilgis");    
			//生成API 文档所在目录
			config.setDocsPath("C:\\新建文件夹");
			// 配置自动生成
			config.setAutoGenerate(Boolean.TRUE);  
			// 执行生成文档
			Docs.buildHtmlDocs(config); 
		}
}

编码规范

JApiDocs是通过解析Java源码来实现的，要使得JApiDocs正确工作，需要你在项目中的Controller书写遵循一定的编码规范，需要在注释里面添加@param 否则生成的文档会乱码。

可以参考我的例子

	/**
	 * xml查询 通过id查询用户信息
	 * @param id
	 * @return
	 * @author ygc
	 */
	@RequestMapping("/queryUserById")
	@Transactional(propagation=Propagation.SUPPORTS)
	public List<UserInfo>  queryUserById(Integer id) {	
		List<UserInfo> temp=userService.queryUserById(id);
		if(temp!=null){
			return temp;
		}
		return null;
	}

四、生成文档

选择文件夹下的index.html并打开

五、生成结果