可用配置规则

EasyYapi 提供了丰富的配置规则来自定义 API 文档生成。

规则格式

规则以键值对的形式定义在配置文件中：

properties

rule.key=rule_value

部分规则支持 Groovy 脚本进行高级自定义：

properties

rule.key=groovy:``` 
// Groovy 脚本
it.name() + " - 自定义后缀"
```

值格式

引擎根据值的形态决定如何求值，而不是根据键——不存在"某个键固定某种执行模式"的说法。同一个键可以用下面任意一种格式书写，选择依据是：值是静态的、已经存在于元素上，还是需要从项目代码中计算得出。

格式	含义	示例
（字面量）	值原样注入（默认）；多行值使用三反引号	`field.ignore=true`
`groovy:`	以 `it` 上下文执行 Groovy 脚本，脚本返回值作为规则值	`method.additional.header=groovy: it.name()`
`@Fqn` / `@Fqn#attr`	从元素上的注解取值（默认取 `value()` 属性）	`method.doc=@io.swagger.v3.oas.annotations.Operation#description`
`#tag`	从元素上的 JavaDoc/KDoc 标签取值	`method.return=#return`
`${n}`	替换为 `#regex:` 过滤器捕获的分组	`json.rule.convert[#regex:ApiResult<(.*?)>]=${1}`

过滤器与值的区别

不要混淆 [...] 中的过滤器标记（$class:、@、#tag、#regex:、!）——它们决定规则是否生效；与值位置上相同的 @ / # 标记——它们决定值从元素的哪里取值。

API 规则

规则	说明
api.name	设置 API 名称
api.open	设置 API 是否公开
api.status	设置 API 状态
api.tag	设置 API 标签

类规则

规则	说明
class.doc	设置类文档
class.is.ctrl ~~已废弃~~	判断是否为控制器（class.is.spring.ctrl 的别名）
class.is.spring.ctrl	判断是否为 Spring 控制器
class.is.feign.ctrl	判断是否为 Feign 客户端
class.is.jaxrs.ctrl	判断是否为 JAX-RS 资源
class.is.quarkus.ctrl	判断是否为 Quarkus 资源
class.is.grpc	判断是否为 gRPC 服务
class.prefix.path	设置类前缀路径

字段规则

规则	说明
field.default.value	设置字段默认值
field.demo	设置字段示例值
field.doc	设置字段文档
field.ignore	忽略字段
field.mock	设置字段 Mock 值
field.name	设置字段名称
field.name.prefix	设置字段名称前缀
field.name.suffix	设置字段名称后缀
field.required	设置字段是否必填
field.order	设置字段顺序
field.order.with	设置字段排序比较器
field.advanced	设置字段高级信息
field.max.depth	设置字段最大递归深度

方法规则

规则	说明
method.doc	设置方法文档
method.return	设置方法返回类型
method.return.main	指定 @return 文档注释放置的字段
method.content.type	设置内容类型
method.default.http.method	设置默认 HTTP 方法
method.additional.header	添加额外请求头
method.additional.param	添加额外参数
method.additional.response.header	添加额外响应头

参数规则

规则	说明
param.default.value	设置参数默认值
param.demo	设置参数示例值
param.doc	设置参数文档
param.http.type	设置参数 HTTP 类型
param.ignore	忽略参数
param.name	设置参数名称
param.required	设置参数是否必填
param.type	设置参数类型
param.mock	设置参数 Mock 值
param.max.depth	设置参数最大递归深度

枚举规则

规则	说明
enum.use.custom	自定义枚举值

JSON 规则

规则	说明
json.rule.convert	类型转换
json.additional.field	添加额外字段
json.unwrapped	处理 @JsonUnwrapped

其他规则

规则	说明
folder.name	设置文件夹名称
module ~~已废弃~~	设置模块名称（yapi.project 的别名）
ignore	忽略 API
path.multi	多路径支持
export.after	导出后回调
http.call.before	请求前回调
http.call.after	请求后回调
constant.field.ignore	忽略常量字段
endpoint.prefix.path	设置端点前缀路径

Postman 规则

规则	说明
postman.host	设置 Postman 基础 URL
postman.prerequest	前置请求脚本
postman.test	测试脚本
postman.class.prerequest	类级别前置请求脚本
postman.class.test	类级别测试脚本
postman.collection.prerequest	集合级别前置请求事件
postman.collection.test	集合级别测试事件
postman.format.after	格式化后事件

YApi 规则

规则	说明
yapi.project	设置 YApi 项目
yapi.export.before	导出前事件
yapi.save.before	保存前事件
yapi.save.after	保存后事件

渠道专用规则

OpenAPI

规则	说明
`openapi.info.title`	文档标题
`openapi.info.version`	文档版本
`openapi.info.description`	文档描述
`openapi.server.url`	OpenAPI `servers` 中的地址
`openapi.host`	服务器地址的旧别名
`openapi.format.after`	格式化完成、序列化之前执行的事件

Hoppscotch

规则	说明
`hopp.host`	覆盖集合 Host
`hopp.prerequest`、`hopp.class.prerequest`、`hopp.collection.prerequest`	接口、类、集合级请求前脚本
`hopp.test`、`hopp.class.test`、`hopp.collection.test`	接口、类、集合级响应测试
`hopp.format.after`	集合格式化后执行的事件

ApiPost

规则	说明
`apipost.project`	目标项目 id，覆盖 ApiPost 设置中配置的项目
`apipost.host`	ApiPost 开放接口地址覆盖；仅用于拼装开放接口请求
`apipost.server.url`	被导出 API 的基础地址，写入文档的 host/base_path
`apipost.export.before`	导出开始前触发一次的事件
`apipost.save.before`	推送单个接口前触发，`document` 绑定可被修改
`apipost.save.after`	推送单个接口后触发，暴露 `content` 与 `result`

Custom 框架

Custom 是默认关闭的框架，提取逻辑由 custom.* 规则控制。主要规则包括 custom.class.is.api、custom.method.is.api、custom.http.method、custom.path 和 custom.param.* 绑定/命名规则；同时提供 custom.class.parse.before、custom.class.parse.after、custom.method.parse.before、custom.method.parse.after 和 custom.export.after 生命周期钩子。

详见 Custom 框架，其中包含完整示例以及从旧版 mdoc.* 通用导出规则迁移的方法。

可用配置规则 ​

规则格式 ​

值格式 ​

API 规则 ​

类规则 ​

字段规则 ​

方法规则 ​

参数规则 ​

枚举规则 ​

JSON 规则 ​

其他规则 ​

Postman 规则 ​

YApi 规则 ​

渠道专用规则 ​

OpenAPI ​

Hoppscotch ​

ApiPost ​

Custom 框架 ​