还在用丝袜哥(Swagger)做API文档?快来看看这款帮你减少百分之九十工作量的开源工具!

语言: CN / TW / HK

theme: channing-cyan

「这是我参与2022首次更文挑战的第5天,活动详情查看:2022首次更文挑战

提一嘴Swagger

    相信不少的小伙伴都会在日常工作中写API文档,确实这个文档很有必要去写,便于项目的维护,在我们提桶的时候,接盘侠可以轻松地接管我们的项目。说起API文档,我们脑海中想到的就是肯定是Swagger,他以前确实统治了江湖很久,因为他的确很方便,也很智能,但是吧,你写多了总感觉哪里不对劲,是的,他的代码侵入性太强,而且要写大量重复的注释,那我最近在写的一个项目来说,简直是程序员的梦魇。 在这里插入图片描述     这只是一个实体类的一部分,还有service、controller的这些注解我就不一一列举了,侵入性太强,注释繁多,而且你在编译以后还是存在于代码中不会被擦除。     于是乎,我有一次在写代码(摸鱼)的时候,偶然发现一个Gitee上的高赞API文档,链接:smart-doc 在这里插入图片描述

主角smart-doc

    smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具,划重点了,他还支持Dubbo RPC接口文档,遥想当年,Swagger要想支持Dubbo的话必须要自己修改和拓展,官方是不支持的。于是我就照着官方文档给的案例,去部署生成了一下API文档,真香!

新建smart-doc.json

    我们需要新建一个smart-doc.json来写一些配置,我这里也给出一份模板,有需要的铁汁们直接cv改改即可。 json { //服务器地址 "serverUrl": "http://127.0.0.1", //是否用严格模式,严格模式强制检查注释 "isStrict": false, //所有接口文档合并生成到一个文档 "allInOne": true, //文档的输出路径 "outPath": "src/main/resources/static/doc", //指定项目名称,用于显示在文档中 "projectName": "test-smart-doc" }

引入依赖

xml <plugin> <groupId>com.github.shalousun</groupId> <artifactId>smart-doc-maven-plugin</artifactId> <version>2.2.2</version> <configuration> <!--指定生成文档使用的配置文件--> <configFile>./src/main/resources/smart-doc.json</configFile> </configuration> <executions> <execution> <!--不需要在编译项目时自动生成文档可注释phase--> <phase>compile</phase> <goals> <goal>html</goal> </goals> </execution> </executions> </plugin> ## 测试 在这里插入图片描述     双击smart-doc即可生成java普通(为了区别于Dubbo)的文档,他的UI界面也不丑,大致长这样。 在这里插入图片描述     我们几乎没有写任何注释代码,就自动生成了一个API文档,没有任何侵入性。

smart-doc强在哪?

    smart-doc对比传统一哥Swagger究竟有什么不同? 1. smart-doc主要是基于源代码和JAVADOC标注注释来生成文档,是在开发期或者是项目的编译期执行生成文档,意味着你是在项目编译完以后你在源码里面是找不到smart-doc的任何依赖的,0侵入性。 2. swagger主要原理是利用JAVA的注解和反射机制去生成文档,这种方式侵入性太强。

    这也就是为什么我刚刚什么注解都没写,但是依然可以生成合格的API文档,于是乎我马上把Swagger换成了smart-doc,只能说真香,再也不用写@ApiModel这种注解了。