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：

name	value	required	desc
Content-Type	application/json	YES

Query：

name	value	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：

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