JApiDocs教程

前言

作为一名优秀的程序员来说，由于涉及到要与前端进行对接，所以避免不了的就是写接口文档。写完接口文档，一旦代码返回结果，参数等出现变动，接口文档还得随之改动，十分麻烦，违背了我们简单，快速，低bug的开发初衷。
所以，自动生成接口文档的工具就出现了。大家最熟悉的应该就是swagger了，我并没有使用过swagger，虽然它比较健壮，稳定。但是由于它的规范很复杂，需要将代码变动的地方也很多。所以我使用了JApiDocs这个工具来为我的项目自定生成接口文档。
它的优点就是，相对于springboot以及ssm开发模式而言，它的改动都不是很大，规范一下代码，就可以轻松获取接口文档了。
问题：参数为实体类对象时，直接显示对象里的所有字段。而真正使用的字段只有一部分。大体没什么毛病，界面也很简洁美观。大家如果有解决参数精准显示的想法，可以在评论区一起讨论下。

一、Maven依赖

<!--  JApiDocs  -->
<dependency><groupId>io.github.yedaxia</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 {@Autowiredprivate 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;  //提醒idprivate String remindContent;  //提醒信息private java.sql.Timestamp remindTime;  //提醒时间
}

效果图：

注：字段后的注释一定都要写上，否则会报下面的错误：

（3）使用@RequestBody 注解json格式的参数

效果图：

3. 返回对象

（1）@RestController 或 @ResponseBody

返回json数据类型
例：

/*** 用户接口*/
@RequestMapping("/test")
@RestController
public class testInterface {@Autowiredprivate 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” io.github.yedaxia.apidocs.exception.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

可以通过 pandoc 把 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{@Overridepublic 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*/

具体如何实现自定义方法注释，类注释。可以参考下面的文章：

https://blog.csdn.net/qq_38675373/article/details/105886922

JApiDocs官方文档地址：

https://japidocs.agilestudio.cn/#/

自动生成接口文档之JApiDocs教程相关推荐

springboot 之自动生成接口文档工具JApiDocs
JApiDocs是一个无需额外注解.开箱即用的SpringBoot接口文档生成工具简易使用方法 1.添加依赖 <dependency><groupId>io.github.y ...
SpringBoot自动生成接口文档
跟大家介绍一个自动生成接口文档的工具包,作者的理念是注释即文档,在写代码的时候写上注释,项目启动后就会生成接口文档,非常方便,省去了Swagger写注解的过程. 仓库地址:https://github ...
Django框架深入了解_05 (Django中的缓存、Django解决跨域流程(非简单请求，简单请求)、自动生成接口文档)(二)
二.跨域: 回到顶部跨域知识介绍: 点我以前博客跨域解决方法:CORS:跨域资源共享 CORS请求分类(简单请求和非简单请求) 简单请求(simple request):只需要在头信息之中增加一个 ...
Django框架深入了解_05 (Django中的缓存、Django解决跨域流程(非简单请求，简单请求)、自动生成接口文档)(一)
阅读目录一.Django中的缓存: 前戏: Django中的几种缓存方式: Django中的缓存应用: 二.跨域: 跨域知识介绍: CORS请求分类(简单请求和非简单请求) 示例: 三.自动生成接口 ...
Spring Boot（九）Swagger2自动生成接口文档和Mock模拟数据
一.简介在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
idea swagger生成接口文档_Spring Boot（九）Swagger2自动生成接口文档和Mock模拟数据...
一.简介在当下这个前后端分离的技术趋势下,前端工程师过度依赖后端工程师的接口和数据,给开发带来了两大问题: 问题一.后端接口查看难:要怎么调用?参数怎么传递?有几个参数?参数都代表什么含义? 问题二 ...
java自动生成接口文档
java自动生成接口文档 maven依赖工具类展示效果首页接口页在平时的开发过程中必定要写接口文档作为程序员最烦的2件事 1.别人让你写接口文档 2.接手别人的项目没有接口文档由此可见 ...
DRF 自动生成接口文档
Python微信订餐小程序课程视频 https://edu.csdn.net/course/detail/36074 Python实战量化交易理财系统 https://edu.csdn.net/cou ...
Django DRF 自动生成接口文档
文章目录 1. 引子 2. 自动生成接口文档 3. 文档描述说明的定义位置 1. 引子前端请求的url由谁来写 url 主要有后台来写,写完给前端: 如果后台查询数据,需要借助查询条件才能查询前端需 ...

自动生成接口文档之JApiDocs教程

JApiDocs教程

前言

一、Maven依赖

二、代码规范

1. 分组名称 @description

2. 接口参数（JApiDocs 会通过 @param 来寻找接口参数和进一步解析参数的内容）

（1）格式：接口参数 @param 字段字段解释

（2）在相应的bean对象里添加注释

（3）使用@RequestBody 注解json格式的参数

3. 返回对象

（1）@RestController 或 @ResponseBody

（2）请求类型

4、高级配置

（1）@ApiDoc

a.实现

b.其他设置

(2)@Ignore (忽略Controller，接口，字段)

三、配置参数

四、导出格式

（1）Markdown

（2）导出 pdf 或者 word

五、自定义代码模板

（1）定义代码模板

（2）选择新的模板

六、添加更多功能

（1）实现 IPluginSupport 接口

（2）添加插件

七、问题的解决

1、如何排查错误？

2、多模块找不到相关类源码？

八、自定义注释模板

（1）Live Templates

（2）File Header

自动生成接口文档之JApiDocs教程相关推荐

最新文章

热门文章

自动生成接口文档之JApiDocs教程

JApiDocs教程

前言

一、Maven依赖

二、代码规范

1. 分组名称 @description

2. 接口参数（JApiDocs 会通过 @param 来寻找接口参数和进一步解析参数的内容）

（1）格式：接口参数 @param 字段 字段解释

（2）在相应的bean对象里添加注释

（3）使用@RequestBody 注解json格式的参数

3. 返回对象

（1）@RestController 或 @ResponseBody

（2）请求类型

4、高级配置

（1）@ApiDoc

a.实现

b.其他设置

(2)@Ignore (忽略Controller，接口，字段)

三、配置参数

四、导出格式

（1）Markdown

（2）导出 pdf 或者 word

五、自定义代码模板

（1）定义代码模板

（2）选择新的模板

六、添加更多功能

（1）实现 IPluginSupport 接口

（2）添加插件

七、问题的解决

1、如何排查错误？

2、多模块找不到相关类源码？

八、自定义注释模板

（1）Live Templates

（2）File Header

自动生成接口文档之JApiDocs教程相关推荐

最新文章

热门文章

（1）格式：接口参数 @param 字段字段解释