JApiDocs教程
前言
作为一名优秀的程序员来说,由于涉及到要与前端进行对接,所以避免不了的就是写接口文档。写完接口文档,一旦代码返回结果,参数等出现变动,接口文档还得随之改动,十分麻烦,违背了我们简单,快速,低bug的开发初衷。
所以,自动生成接口文档的工具就出现了。大家最熟悉的应该就是swagger了,我并没有使用过swagger,虽然它比较健壮,稳定。但是由于它的规范很复杂,需要将代码变动的地方也很多。所以我使用了JApiDocs这个工具来为我的项目自定生成接口文档。
它的优点就是,相对于springboot以及ssm开发模式而言,它的改动都不是很大,规范一下代码,就可以轻松获取接口文档了。
问题:参数为实体类对象时,直接显示对象里的所有字段。而真正使用的字段只有一部分。大体没什么毛病,界面也很简洁美观。大家如果有解决参数精准显示的想法,可以在评论区一起讨论下。
一、Maven依赖
io.github.yedaxia
japidocs
1.4.3
二、代码规范
为什么要进行代码规范?
JApiDocs会根据固定的格式,来为我们解析出相应的接口文档,相对比与swagger来说,JApiDocs的格式相对来说是很简单的,springboot开发的项目使用起来改动不大,同时还能使我们的代码规范,简洁,一致。所以我们只要遵循以下几点就能得到规整的接口文档了。
以下都是针对于controller模块:
1. 分组名称 @description
注:官方文档中注明分组名称@description,但是实际应用中不需要加入注解,像下例所示,直接写注释即可。(类上写不写都行,方法上如果加上@description反而不显示)
例:
/**
* 用户接口
*/
/*注意:这里不能空行,否则注释名无法显示*/
@RequestMapping("test")
@Controller
public class testInterface {
@Autowired
private RoleService roleService;
/**
* 保存用户
*/
@PostMapping("advice