配置

支持的规则

    规则的key 规则目标(上下文it) 版本 规则描述
    api.name method v1.4.1+ 设置api的名称
    api.tag method v0.7.5+ 标记接口tag
    api.open method v1.9.4+ 标记接口是否公开
    api.status method v0.8.0+ 标记接口status(应返回done/undone)
    class.doc class v1.3.0+ 类上的额外注释
    class.is.ctrl method v2.0.8+ 允许导出指定类中的api
    class.postman.prerequest class v1.9.5+ 设置postman·folder上的prerequest
    class.postman.test class v1.9.5+ 设置postman·folder上的test
    class.prefix.path class v1.3.0+ 设置API请求前缀
    collection.postman.prerequest class v1.9.5+ 设置postman·collection上的prerequest
    collection.postman.test class v1.9.5+ 设置postman·collection上的test
    constant.field.ignore field v1.3.8+ 忽略常量字段
    enum.use.custom class v2.4.1+ 用于设置使用@see枚举类型时的默认取值字段, 优先级高于enum.use.by.type
    enum.use.by.type class v2.4.1+ 用于设置使用@see枚举类型时的默认使用类型一致的字段, 优先级低于enum.use.custom
    enum.use.ordinal class v2.2.1+ 用于设置使用@see枚举类型时的默认使用ordinal作为取值
    enum.use.name class v2.2.1+ 用于设置使用@see枚举类型时的默认使用name作为取值
    field.advanced field v2.2.8+ 提供yapi的高级设置信息
    field.default.value - v1.7.1+ 用以设置字段的默认值
    field.demo - v1.9.3+ 用以设置字段的示例值
☆field.doc field v0.7.2+ 字段的额外注释
    field.ignore field v2.0.0+ 忽略字段(设置某些字段不出现在json中,或不需要请求时给出)
☆field.mock field v1.4.2+ 生成yapimock信息
    field.mock.resolveProperty - v1.4.2+ 用以开关是否解析field.mock规则结果中的占位符
    field.name field v0.7.2+ 设置输出的字段名(用于json中字段名与类中字段名不一致)
    field.required field v0.7.3+ 字段是否为必须(即不可为空)
    field.order field v2.6.4+ 用于指定字段顺序
    field.order.with field v2.6.4+ 用于设置字段顺序
    field.type field v2.6.4+ 用于设置字段实际数据类型
    folder.name method v1.9.2+ 设置api所属文件夹
    ignore class/method v0.7.2+ 忽略API
☆json.rule.convert - v0.7.2+ 用于设置某些类型转换为其他类型处理, 通常用于使用了Spring的自定义类型转换器的情况
    json.rule.enum.convert class v1.2.0+ 用于枚举类型的特殊转换
    json.rule.field.ignore field v0.7.2+ 忽略字段(设置某些字段不出现在json中,或不需要请求时给出) 已废弃, 使用field.ignore代替
    json.rule.field.name field v0.7.2+ 设置输出的字段名(用于json中字段名与类中字段名不一致)
    mdoc.class.filter class v0.9.5+ 选择哪些类可以导出方法文档(rpc)
    mdoc.method.filter method v0.9.5+ 选择哪些方法可以导出方法文档(rpc)
    mdoc.method.path method v0.9.5+ 设置方法文档(rpc)的路径
    mdoc.method.http.method method v0.9.5+ 设置方法文档(rpc)HTTP请求方式
    method.additional.header method v1.3.0+ API需要额外的header
{name: "header name",value: "",desc: "",required:false, demo:""}
    method.additional.param method v1.3.0+ API需要额外的参数
{name: "param name",value: "defaultValue",desc: "",required:false}
    method.additional.response.header method v1.3.0+ API的响应包含额外的header
{name: "header name",value: "",desc: "",required:false, demo:""}
    method.content.type - v1.9.7+ 用以设置API请求的content-type
    method.default.http.method method v1.4.2+ 设置默认的api的HttpMethod
    method.doc method v0.7.2+ 方法(api)的额外注释
☆method.return.main method v1.3.8+ 设置返回值的核心主体
☆method.return method v1.6.1+ 设置返回值的类型
    module class v0.7.2+ 为api分组
    param.default.value arg v1.3.0+ API参数的默认值
    param.demo - v1.9.3+ 用以设置参数的示例值
    param.doc arg v1.3.0+ 参数的额外注释
    param.http.type arg v2.0.0+ 用于设置API参数在HTTP请求中的类型
    param.ignore arg v1.3.0+ 忽略API参数
    param.required arg v0.7.3+ API参数是否为必须(即不可为空)
    path.multi method v1.9.2+ 当API有多个路径时如何选择
    postman.host class v1.5.2+ 设置postmanAPI的host
    postman.prerequest class v1.9.5+ 设置postmanAPI的prerequest
    postman.test class v1.9.5+ 设置postmanAPI的test

支持的简单配置

简单配置无上下文

    规则的key 版本 配置类型 规则描述 示例
    yapi.server v2.2.1+ string 设置yapi地址,优先级高于setting. 可用于多个项目要导入不同yapi的情况 yapi.server=http://yapi.itangcent.com/
    yapi.token.$module v2.5.8+ string 设置yapi模块的token,优先级高于setting. 可用于多人共享账号的情况下简化使用 yapi.token.xxx=01234567890123456789
    dev v2.2.1+ bool 启动开发模式,打印更详细的日志 dev=true
    max.deep v2.3.6+ int 解析json时最大深度,默认6 max.deep=8
    max.elements v2.3.6+ int 解析json时最大字段数,默认256 max.elements=512
    json.cache.disable v2.1.0+ bool 禁用json解析缓存 json.cache.disable=true
    http.timeOut v2.1.0+ int http请求的超时时间(s),优先级高于setting http.timeOut=5
    auto.format.url v2.1.0+ bool 导入yapi时是否格式化url,确保url以/开始，且将[a-zA-Z0-9-/_:.{}?=!]之外的字符替换为/ auto.format.url=false
    field.mock.resolveProperty v2.1.0+ bool 是否处理yapi mock信息中的占位符${xxx} field.mock.resolveProperty=true
    api.tag.delimiter v2.1.0+ string yapi tag的分割符, 默认为, api.tag.delimiter=,#
    ignore_static_and_final_field v2.1.0+ bool 插件默认会忽略static final字段, 设置为false可以改变此行为 ignore_static_and_final_field=false
    ignore_irregular_api_method v2.5.4+ bool 插件默认会忽略方法名与Object中基础方法名相同的API, 设置为false可以改变此行为 ignore_irregular_api_method=false
    doc.source.disable v2.5.5+ bool 设置为true可以阻止插件读取注释 doc.source.disable=true

支持的回调

部分回调方法中可能没有it, 但可能会有附加的上下文供使用

    规则的key 规则目标(上下文it) 附加上下文 版本 规则描述
    api.class.parse.before class 无 v2.2.8+ 解析api前回调
    api.class.parse.after class 无 v2.2.8+ 解析api后回调
    api.method.parse.before method 无 v2.2.8+ 解析api方法前回调
    api.method.parse.after method 无 v2.2.8+ 解析api方法后回调
    api.param.parse.before param 无 v2.2.8+ 解析api参数前回调
    api.param.parse.after param 无 v2.2.8+ 解析api参数后回调
    export.after method api v2.0.1+ 每个api导出完成后回调
    http.call.before 无 request v1.9.0+ http请求前回调
    http.call.after 无 request, response v1.9.0+ http请求后回调
    json.class.parse.before class 无 v2.2.8+ 解析类型前回调
    json.class.parse.after class 无 v2.2.8+ 解析类型后回调
    json.field.parse.before field 无 v2.2.8+ 解析类型字段前回调
    json.field.parse.after field 无 v2.2.8+ 解析类型字段后回调
    json.method.parse.before method 无 v2.2.8+ 解析类型方法 (getter|setter)前回调
    json.method.parse.after method 无 v2.2.8+ 解析类型方法(getter|setter)后回调
    yapi.export.before 无 无 v2.0.1+ 导出到yapi之前回调

NOTES: 本地文件配置

规则语法

简单规则

  • # 读取注释上的tag

    • 如 #fake对应取的注释如下:

      /**
* @fake
*/

  • @ 读取注解

    • @xxx 读取方法或字段上的注解,如@org.springframework.web.bind.annotation.RequestMapping

      @RequestMapping("path")
public class FakeClass{...}

    • @xxx#yyy 读取方法或字段上的注解中的attr值,如@org.springframework.web.bind.annotation.RequestMapping#value

      @RequestMapping(value = "path")
public class FakeClass{...}

  • 字面量

    • boolean如: api.open=true
    • string如: api.status=done

高级脚本规则

  • 由于JDK11后js引擎可能缺失, 故推荐使用groovy作为首选
  • groovy规则为 groovy:groovyScript
  • js规则为 js:jsScript
  • 脚本中可用工具/对象: tools
  • 脚本调试: script-executor
    markdown自定义规则
    api.name