SpringBoot接口文档生成插件：EasyYapi（支持yapi、Markdown、Postman）

优势

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

准备工作

• IDEA安装插件：EasyYapi GitHub

规范

1. JavaDoc规范 遵循JavaDoc规范（其实就是开发过程中把字段注释和方法注释写好）。例如：/**- 课程列表对象- @author xxx- @date 2022/9/26 22:23 */ public class CourseListVO {/**- 课程id */ private String courseId; … }
2. 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：
namevaluerequireddescContent-Typeapplication/jsonYES
Query：
namevaluerequireddescuserIdNO用户idphoneNO手机号accountNO账号nickNameNO昵称
RequestBody
nametypedescidstring
Request Demo：

{"id":""}

RESPONSE

Header：
namevaluerequireddesccontent-typeapplication/json;charset=UTF-8NO
Body：
nametypedesccodeintegermsgstringdataobject|─idstring|─titlestring课程标题|─subTitlestring子标题|─bannerImgsarray顶部导航图数组|─string|─detailstring详情富文本|─freeboolean是否免费 0-否，1-是|─pricenumber价格|─readCountinteger阅读量|─hotStarinteger热度|─payCountinteger被购买次数systemTimestring
Response Demo：

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