听说丝袜哥(swagger)不好用试试JApiDocs吧

一介绍

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

有人嫌弃使用Swagger 要使用很多注解，当项目比较大时，光注解就需要写很多时间，然后 JApiDocs 完全可以使用Java原生的代码代替它；

官方 giee地址： https://gitee.com/yeguozhong/JApiDocs

二入门使用

2.1引入依赖

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

2.2 在VO上加上java注释

/*** @Author lsc* <p> 测试实体 </p>*/
public class TestVo  {/** 测试名称**/private String testName;/** 测试年龄 **/private Long testAge;/** 测试时间 **/private LocalDateTime testTime;// 省略 set get
}

2.3 控制层加上java注释

/*** @Author lsc* <p>测试 </p>*/
@RestController
public class TestController {/*** 测试get* @param testVo*/@GetMapping(value = "info")public ResponseEntity<TestVo> testGet(TestVo testVo){return ResponseEntity.ok().body(testVo);}/*** 测试get参数* @param id*/@GetMapping(value = "info/test")public ResponseEntity<Long> test(@RequestParam Long id){return ResponseEntity.ok().body(id);}/*** 测试post* @param testVo*/@PostMapping(value = "info")public ResponseEntity<Long> testPost(@RequestBody TestVo testVo){return ResponseEntity.ok().body(1L);}/*** 测试delete* @param id*/@DeleteMapping(value = "info/{id}")public ResponseEntity<Long> testPost(@PathVariable Long id){return ResponseEntity.ok().body(1L);}}

2.4 生成文档

 public static void main(String[] args) {// 1. 创建生成文档的配置DocsConfig config = new DocsConfig();// 项目所在目录config.setProjectPath("C:/java/zszxz/studys-pringboot/springboot-JApiDocs");// 生成 HTML 接口文档的目标目录config.setDocsPath("C:/mydata/generator/japi");// 自动生成config.setAutoGenerate(Boolean.TRUE);// 项目名config.setProjectName("japi测试项目");// API 版本号config.setApiVersion("V1.0");// 使用 MD 插件，额外生成 MD 格式的接口文档config.addPlugin(new MarkdownDocPlugin());// 2. 执行生成 HTML 接口文档Docs.buildHtmlDocs(config);}

生成文档目录如下

访问 index 页面

三高级用法

高级用法基本我们都用不到，了解下；

3.1@ApiDoc

默认情况下，JApiDocs仅导出声明@ApiDoc的api。我们之前通过设config.setAutoGenerate（Boolean.TRUE）删除了此限制。

如果不想导出所有api，则可以关闭autoGenerate并将@ApiDoc添加到Controller类或api方法中，以确定需要导出的api。

让我们看看@ApiDoc如何在api方法上工作：

result ：返回的对象类型，它将覆盖SpringBoot的返回对象
url：请求URL，扩展字段，用于支持非SpringBoot项目
method：请求方法，扩展字段，用于支持非SpringBoot项目

示例

@ApiDoc(result = AdminVO.class, url = "/api/v1/admin/login2", method = "post")

将 @ApiDoc 放在非springboot的项目上就是很好的选择

3.2 @Ignore

如果不想导出实体上的某个字段就可以使用@Ignore 注解

示例

public class TestVo  {/** 测试名称**/@Ignoreprivate String testName;
}

3.3 导出 Markdown

在配置时加上下面这行代码就可以生成 Markdown 文件

config.addPlugin(new MarkdownDocPlugin());

最后

关于本教程示例源码合并在 springboot 系列教程源码： https://github.com/zszxz/study-springboot

知识追寻者开源的权限管理系统: https://github.com/zszxz/zboot

希望大家多多支持，给个start！！

欢迎关注我的公众号：知识追寻者；