- 作为一名优秀的程序员来说，由于涉及到要与前端进行对接，所以避免不了的就是写接口文档。写完接口文档，一旦代码返回结果，参数等出现变动，接口文档还得随之改动，十分麻烦，违背了我们简单，快速，低bug的开发初衷。
- 所以，自动生成接口文档的工具就出现了。大家最熟悉的应该就是swagger了，我并没有使用过swagger，虽然它比较健壮，稳定。但是由于它的规范很复杂，需要将代码变动的地方也很多。所以我使用了JApiDocs这个工具来为我的项目自定生成接口文档。
- 它的优点就是，相对于springboot以及ssm开发模式而言，它的改动都不是很大，规范一下代码，就可以轻松获取接口文档了。
- 问题：参数为实体类对象时，直接显示对象里的所有字段。而真正使用的字段只有一部分。大体没什么毛病，界面也很简洁美观。大家如果有解决参数精准显示的想法，可以在评论区一起讨论下。
为什么要进行代码规范？
- JApiDocs会根据固定的格式，来为我们解析出相应的接口文档，相对比与swagger来说，JApiDocs的格式相对来说是很简单的，springboot开发的项目使用起来改动不大，同时还能使我们的代码规范，简洁，一致。所以我们只要遵循以下几点就能得到规整的接口文档了。
以下都是针对于controller模块：
注：官方文档中注明分组名称@description，但是实际应用中不需要加入注解，像下例所示，直接写注释即可。（类上写不写都行，方法上如果加上@description反而不显示）
例：
效果图：
注：注释一定要放在@注解的上面，否则参数会不显示
（1）格式：接口参数 @param 字段 字段解释
例：
效果图：
（2）在相应的bean对象里添加注释
例：
效果图：
注：字段后的注释一定都要写上，否则会报下面的错误：
（3）使用@RequestBody 注解json格式的参数
效果图：
（1）@RestController 或 @ResponseBody
效果图：
（2）请求类型
效果图： 
没有指定具体类型时：
（1）@ApiDoc
a.实现
JApiDocs 默认只导出声明了@ApiDoc的接口，我们前面通过设置config.setAutoGenerate(Boolean.TRUE) 来解除了这个限制。如果你不希望把所有的接口都导出，你可以把autoGenerate设置关闭，在相关Controller类或者接口方法上通过添加@ApiDoc来确定哪些接口需要导出。
b.其他设置
result: 这个可以直接声明返回的对象类型，如果你声明了，将会覆盖SpringBoot的返回对象
stringResult：返回字符串，在返回结果比较简单，而不想创建一个专门的返回类，则可以考虑使用这个属性。
url: 请求URL，扩展字段，用于支持非SpringBoot项目
method: 请求方法，扩展字段，用于支持非SpringBoot项目
例：
例：忽略Controller
在任意一个main入口执行下面的代码：
执行结果类似效果图：
可以通过 pandoc 把 markdown 格式转成 pdf 或者 word 格式。
JApiDocs 除了支持文档导出，目前也支持生成了 Android 和 iOS 的返回对象代码，对应 Java 和 Object-C 语言， 如果你想修改代码模板，可以通过以下的方法：
把源码中library项目resources目录下的代码模板拷贝一份，其中，IOS_表示 Object-C 代码模板，JAVA_开头表示 Java代码， 模板中类似${CLASS_NAME}的符号是替换变量，具体含义你可以结合生成的代码进行理解，然后按照你想要的代码模板进行修改即可。
通过DocsConfig配置模板路径替换成新的模板：
JApiDocs 提供了插件接口，你可以通过插件接口来实现更多丰富的功能，下面介绍如何添加插件：
关闭自动生成config.setAutoGenerate(Boolean.FALSE)，使用@ApiDoc 来一个个接口导出排查问题。
如果源码路径没有全部识别出来，可以通过config.addJavaSrcPath来添加模块的源码路径，注意要添加到src/main/java这一级。
这是我针对JApiDocs，对我的模板进行了一定的调整，以方便对JApiDocs的使用，大家可以参考一下。
具体如何实现自定义方法注释，类注释。可以参考下面的文章：
https://blog.csdn.net/_/article/details/
JApiDocs官方文档地址：
https://japidocs.agilestudio.cn/#/
版权声明：
本文来源网络，所有图片文章版权属于原作者，如有侵权，联系删除。
本文网址：https://www.bianchenghao6.com/java-jiao-cheng/7568.html