SpringBoot接口文档生成插件：EasyYapi（支持yapi、Markdown、Postman）-Toy模板网

这篇具有很好参考价值的文章主要介绍了SpringBoot接口文档生成插件：EasyYapi（支持yapi、Markdown、Postman）。希望对大家有所帮助。如果存在错误或未考虑完全的地方，请大家不吝赐教，您也可以点击"举报违法"按钮提交疑问。

优势

对比手写文档：
略
对比Swagger：
不需要写繁杂的swagger注解，只要求代码注释遵循全球统一的JavaDoc规范
支持导出到Yapi、Postman脚本、Markdown文档、Json

准备工作

IDEA安装插件：EasyYapi GitHub

规范

JavaDoc规范
遵循JavaDoc规范（其实就是开发过程中把字段注释和方法注释写好）。例如：

/**
- 课程列表对象
- @author xxx
- @date 2022/9/26 22:23
  */
  public class CourseListVO {
  
  /**
  - 课程id
    */
    private String courseId;
    …
    }
Controller方法返回值必须表现为泛型，否则生成文档时不能识别具体data对象里面的字段。（也可以在controller层直接返回data，通过全局数据处理封装code和msg）。例如：

/**
* 课程搜索
*
* @return
*/
@PostMapping(“courseSearch”)
public R<Page> courseSearch(@RequestBody CourseSearchForm form, @AppLoginUser LoginUserDTO loginUserDTO) {
return R.ok(courseService.courseSearch(form, loginUserDTO));
}

导出文档

在Controller类或Controller类方法上右键 -> Export Yapi

进阶配置

指定接口前缀、忽略指定参数类型

在项目根目录创建文件：.easy.api.config

# 忽略参数自动注入的参数
param.ignore=groovy:it.type().name()=="cn.xxx.common.core.domain.LoginUserDTO"
# 生成yapi的默认前缀
class.prefix.path=/userCenter

其他更多配置参考官方文档。以下是导出文档的示例。

导出Markdown示例

课程详情

BASIC

Path： /api/course/detail

Method： POST

REQUEST

Headers：

name	value	required	desc
Content-Type	application/json	YES

Query：

name	required	desc
userId	NO	用户id
phone	NO	手机号
account	NO	账号
nickName	NO	昵称

RequestBody

name	type	desc
id	string

Request Demo：

{
  "id": ""
}

RESPONSE

Header：

name	value	required	desc
content-type	application/json;charset=UTF-8	NO

Body：

name	type	desc
code	integer
msg	string
data	object
\|─id	string
\|─title	string	课程标题
\|─subTitle	string	子标题
\|─bannerImgs	array	顶部导航图数组
\|─	string
\|─detail	string	详情富文本
\|─free	boolean	是否免费 0-否，1-是
\|─price	number	价格
\|─readCount	integer	阅读量
\|─hotStar	integer	热度
\|─payCount	integer	被购买次数
systemTime	string

Response Demo：文章来源地址https://www.toymoban.com/news/detail-782149.html

{
  "code": 0,
  "msg": "",
  "data": {
    "id": "",
    "title": "",
    "subTitle": "",
    "bannerImgs": [
      ""
    ],
    "detail": "",
    "free": false,
    "price": 0.0,
    "readCount": 0,
    "hotStar": 0,
    "payCount": 0
  },
  "systemTime": ""
}