本文主要是介绍听说丝袜哥(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!!
欢迎关注我的公众号:知识追寻者;
这篇关于听说丝袜哥(swagger)不好用试试JApiDocs吧的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!