JApiDocs（⾃动⽣成接⼝⽂档神器）
JApiDocs教程
前⾔
作为⼀名优秀的程序员来说，由于涉及到要与前端进⾏对接，所以避免不了的就是写接⼝⽂档。写完接⼝⽂档，⼀旦代码返回结果，参数等出现变动，接⼝⽂档还得随之改动，⼗分⿇烦，违背了我们简单，快速，低bug的开发初衷。
所以，⾃动⽣成接⼝⽂档的⼯具就出现了。⼤家最熟悉的应该就是swagger了，我并没有使⽤过swagger，虽然它⽐较健壮，稳定。但是由于它的规范很复杂，需要将代码变动的地⽅也很多。所以我使⽤了JApiDocs这个⼯具来为我的项⽬⾃定⽣成接⼝⽂档。
它的优点就是，相对于springboot以及ssm开发模式⽽⾔，它的改动都不是很⼤，规范⼀下代码，就可以轻松获取接⼝⽂档了。
问题：参数为实体类对象时，直接显⽰对象⾥的所有字段。⽽真正使⽤的字段只有⼀部分。⼤体没什么⽑病，界⾯也很简洁美观。⼤家如果有解决参数精准显⽰的想法，可以在评论区⼀起讨论下。
⼀、Maven依赖
<!--  JApiDocs  -->
<dependency>
<groupId>daxia</groupId>
<artifactId>japidocs</artifactId>
<version>1.4.3</version>
</dependency>
⼆、代码规范
为什么要进⾏代码规范？
JApiDocs会根据固定的格式，来为我们解析出相应的接⼝⽂档，相对⽐与swagger来说，JApiDocs的格式相对来说是很简单
的，springboot开发的项⽬使⽤起来改动不⼤，同时还能使我们的代码规范，简洁，⼀致。所以我们只要遵循以下⼏点就能得到规整的接⼝⽂档了。
以下都是针对于controller模块：
1. 分组名称 @description
注：官⽅⽂档中注明分组名称@description，但是实际应⽤中不需要加⼊注解，像下例所⽰，直接写注释即可。（类上写不写都⾏，⽅法上如果加上@description反⽽不显⽰）
例：
/**
* ⽤户接⼝
*/
/*注意：这⾥不能空⾏，否则注释名⽆法显⽰*/
@RequestMapping("test")
@Controller
public class testInterface {
@Autowired
private RoleService roleService;
/**
* 保存⽤户
*/
@PostMapping("advice")
public RoleInfo getAdviceList(String docId){
return roleService.FindRoleBydocId(docId);
}
}
效果图：
2. 接⼝参数（JApiDocs 会通过 @param 来寻接⼝参数和进⼀步解析参数的内容）
注：注释⼀定要放在@注解的上⾯，否则参数会不显⽰（1）格式：接⼝参数 @param 字段字段解释
例：
/**
* @description 保存⽤户
* @param docId  医⽣id
*/
@PostMapping("advice")
public RoleInfo getAdviceList(String docId){
return roleService.FindRoleBydocId(docId);
}
效果图：
（2）在相应的bean对象⾥添加注释
例：
public class RemindInfo implements Serializable {
private long remindId;  //提醒id
private String remindContent;  //提醒信息
private java.sql.Timestamp remindTime;  //提醒时间
}
效果图：
注：字段后的注释⼀定都要写上，否则会报下⾯的错误：
（3）使⽤@RequestBody 注解json格式的参数
效果图：
3. 返回对象
（1）@RestController 或 @ResponseBody
返回json数据类型
例：
/**
* ⽤户接⼝
*/
@RequestMapping("/test")
@RestController
public class testInterface {
@Autowired
private RoleService roleService;
/**
* 保存⽤户
* @param docId  医⽣id
*/
@ApiDoc
@PostMapping("advice")
public RoleInfo getAdviceList(String docId){
return roleService.FindRoleBydocId(docId);
}
}
效果图：
（2）请求类型
@PostMapping("advice")/@GetMapping("advice")
public RoleInfo getAdviceList(String docId){
return roleService.FindRoleBydocId(docId);
}
效果图：
没有指定具体类型时：
注：返回参数不能指向不明，如：Object，否则会报
Exception in thread "main" ption.JavaFileNotFoundException: Cannot find java file 的错误。
4、⾼级配置
（1）@ApiDoc
a.实现
文档字符串是什么JApiDocs 默认只导出声明了@ApiDoc的接⼝，我们前⾯通过设置config.setAutoGenerate(Boolean.TRUE) 来解除了这个限制。如果你不希望把所有的接⼝都导出，你可以把autoGenerate设置关闭，在相关Controller类或者接⼝⽅法上通过添加@ApiDoc来确定哪些接⼝需要导出。
b.其他设置
result: 这个可以直接声明返回的对象类型，如果你声明了，将会覆盖SpringBoot的返回对象
stringResult：返回字符串，在返回结果⽐较简单，⽽不想创建⼀个专门的返回类，则可以考虑使⽤这个属性。
url: 请求URL，扩展字段，⽤于⽀持⾮SpringBoot项⽬
method: 请求⽅法，扩展字段，⽤于⽀持⾮SpringBoot项⽬
例：
@ApiDoc(result = AdminVO.class, url = "/api/v1/admin/login2", method = "post")
stringResult 实例，在⽂档中将会⾃动格式化json字符串：
@ApiDoc(stringResult = "{code: 0, data: 'success'}")
@GetMapping(value = "custom-json")
public Map customJsonResult(){}
(2)@Ignore (忽略Controller，接⼝，字段)
例：忽略Controller
@Ignore
public class UserController {
}
三、配置参数
在任意⼀个main⼊⼝执⾏下⾯的代码：
DocsConfig config = new DocsConfig();
config.setProjectPath("your springboot project path"); // 项⽬根⽬录
config.setProjectName("ProjectName"); // 项⽬名称
config.setApiVersion("V1.0");      // 声明该API的版本
config.setDocsPath("your api docs path"); // ⽣成API ⽂档所在⽬录
config.setAutoGenerate(Boolean.TRUE);  // 配置⾃动⽣成
Docs.buildHtmlDocs(config); // 执⾏⽣成⽂档
执⾏结果类似效果图：
四、导出格式
（1）Markdown
config.addPlugin(new MarkdownDocPlugin());
（2）导出 pdf 或者 word
可以通过把 markdown 格式转成 pdf 或者 word 格式。
五、⾃定义代码模板
JApiDocs 除了⽀持⽂档导出，⽬前也⽀持⽣成了 Android 和 iOS 的返回对象代码，对应 Java 和 Object-C 语⾔，如果你想修改代码模板，可以通过以下的⽅法：
（1）定义代码模板
把源码中library项⽬resources⽬录下的代码模板拷贝⼀份，其中，IOS_表⽰ Object-C 代码模板，JAVA_开头表⽰ Java代码，模板中类似${CLASS_NAME}的符号是替换变量，具体含义你可以结合⽣成的代码进⾏理解，然后按照你想要的代码模板进⾏修改即可。
（2）选择新的模板
通过DocsConfig配置模板路径替换成新的模板：
docsConfig.setResourcePath("模板路径");
六、添加更多功能
JApiDocs 提供了插件接⼝，你可以通过插件接⼝来实现更多丰富的功能，下⾯介绍如何添加插件：
（1）实现 IPluginSupport 接⼝
public class CustomPlugin implements IPluginSupport{
@Override
public void execute(List<ControllerNode> controllerNodeList){
// 实现你⾃⼰的功能需求
}
}
（2）添加插件
config.addPlugin(new CustomPlugin());
七、问题的解决
1、如何排查错误？
关闭⾃动⽣成config.setAutoGenerate(Boolean.FALSE)，使⽤@ApiDoc 来⼀个个接⼝导出排查问题。
2、多模块不到相关类源码？
如果源码路径没有全部识别出来，可以通过config.addJavaSrcPath来添加模块的源码路径，注意要添加到src/main/java这⼀级。⼋、⾃定义注释模板
这是我针对JApiDocs，对我的模板进⾏了⼀定的调整，以⽅便对JApiDocs的使⽤，⼤家可以参考⼀下。
（1）Live Templates
/**
* TODO
* @create_by: 作者名字
* @create_time: $date$ $time$
* $params$
* @return $return$
*/
（2）File Header
/**
* @Author 作者名字
* @Date ${DATE} ${TIME}
* @description  ${description}
* @Version 1.0
*/
具体如何实现⾃定义⽅法注释，类注释。可以参考下⾯的⽂章：
JApiDocs官⽅⽂档地址：

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。