JApiDocs 代替 Swagger 使用, 简单易操作

1. JApiDocs 代替 Swagger 原因

1. 简洁化: 体现在原有代码之上的无修饰性, 代码即是文档的思想.
2. 方便性: 体现在无痛集成的特点, 以及分钟即用的特点.
3. 规范性: 摒弃 Swagger 的繁琐性, 就必须接受 JApiDocs 的代码注释返回值等全面的规范性.
4. 可配性: 体现在配置可选择性:
   4.1 是否自动进行配置.
   4.2 是否使用自定义模板.
   4.3 导出样式的多样性.

2. JApiDocs 使用

中文网
https://japidocs.agilestudio.cn/#/zh-cn/

2.1 实例样子

2.2 导包

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

2.3 注意事项

1. POJO (Bean) 类中的每个属性最好都加上注解. 注解在上在后都可以.
2. Controller 层
   2.1 请求参数: 是通过注释中 @param 来获取的.
   2.2 返回值: 返回值必须指定确定的返回对象. Result 改为 Result<User>. (这里的返回对象可以是自己自定义的, 也可以是 JApiDocs 带的 ApiResult<>)

2.4 形成 API 文档

一个 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); // 执行生成文档