springboot 之自动生成接口文档工具JApiDocs

JApiDocs是一个无需额外注解、开箱即用的SpringBoot接口文档生成工具

简易使用方法

1.添加依赖

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

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);  // 配置自动生成
config.addPlugin(new MarkdownDocPlugin());
Docs.buildHtmlDocs(config); // 执行生成文档

3.执行main函数，查看文档

我自己的代码

//类1
@Data
public class UserVO {private Integer age;    //用户年龄private String  name;   //姓名
}//类2
/*** 测试APIdoc*/
@RestController
@RequestMapping(value = "testapi")
public class TestController {/*** GET测试*/@GetMapping(value = "testGET")public UserVO testGET(){UserVO userVO = new UserVO();userVO.setAge(12);userVO.setName("小明");return  userVO;}/*** POST测试* @param userinfo*/@PostMapping(value = "testPOST")public String testPOST(@RequestBody UserVO userinfo){return "post";}/*** 测试POST没有注解* @param param* @return*/@PostMapping(value = "testPOSTNO", produces = "application/json")public int testPOSTnoAno(String param){return 3;}public void test(){System.out.println("000000");}
}//main函数public static void main(String[] args) {SpringApplication.run(DemoApplication.class, args);DocsConfig config = new DocsConfig();config.setProjectPath("D:\\ProgramSoft\\IDEA\\java_project\\apidoc"); // 项目根目录config.setProjectName("demo"); // 项目名称config.setApiVersion("V1.0");       // 声明该API的版本config.setDocsPath("D:\\ProgramSoft\\IDEA\\java_project\\apidoc"); // 生成API 文档所在目录config.addPlugin(new MarkdownDocPlugin());config.setAutoGenerate(Boolean.TRUE);  // 配置自动生成Docs.buildHtmlDocs(config); // 执行生成文档}

结果展示：

1. 分组名称 @description

建议不用这个

2. 接口参数@param

JApiDocs 会通过 @param 来寻找接口参数和进一步解析参数的内容

注：注释一定要放在@注解的上面，否则参数会不显示

/*** @description 保存用户* @param docId  医生id*/
@PostMapping("advice")
public RoleInfo getAdviceList(String docId){return roleService.FindRoleBydocId(docId);
}

3.高级配置

（1）@ApiDoc
a.实现
JApiDocs 默认只导出声明了@ApiDoc的接口，我们前面通过设置config.setAutoGenerate(Boolean.TRUE) 来解除了这个限制。如果你不希望把所有的接口都导出，你可以把autoGenerate设置关闭，在相关Controller类或者接口方法上通过添加@ApiDoc来确定哪些接口需要导出。

b.其他设置
result: 这个可以直接声明返回的对象类型，如果你声明了，将会覆盖SpringBoot的返回对象
stringResult：返回字符串，在返回结果比较简单，而不想创建一个专门的返回类，则可以考虑使用这个属性。
url: 请求URL，扩展字段，用于支持非SpringBoot项目
method: 请求方法，扩展字段，用于支持非SpringBoot项目

例：

@ApiDoc(result = AdminVO.class, url = "/api/v1/admin/login2", method = "post")
stringResult 实例，在文档中将会自动格式化json字符串：
@ApiDoc(stringResult = "{code: 0, data: 'success'}")
@GetMapping(value = "custom-json")
public Map customJsonResult(){}

(2)@Ignore (忽略Controller，接口，字段)
例：忽略Controller

@Ignore
public class UserController {
}

4.如何排查错误？

关闭自动生成config.setAutoGenerate(Boolean.FALSE)，使用@ApiDoc 来一个个接口导出排查问题。

在IDEA下正常写代码，注释好方法即可.

当然，以上是简易版的，如果想控制更详细参数，建议读一下中文介绍，也不多
中文介绍

参考其他文章

在此对作者表示感谢，方便了整理文档