框架支持

基于性能考虑, 内置推荐配置并不会覆盖所有框架的所有功能
如需增加对指定框架的支持, 参考配置

Spring Boot

在推荐配置中有很多 spring-boot 相关的配置

处理HttpEntity/RequestEntity/ResponseEntity

properties

#resolve HttpEntity/RequestEntity/ResponseEntity
###set resolveProperty = false
json.rule.convert[#regex:org.springframework.http.HttpEntity]=java.lang.Object
json.rule.convert[#regex:org.springframework.http.HttpEntity<(.*?)>]=${1}
json.rule.convert[#regex:org.springframework.http.RequestEntity<(.*?)>]=${1}
json.rule.convert[#regex:org.springframework.http.RequestEntity]=java.lang.Object
json.rule.convert[#regex:org.springframework.http.ResponseEntity<(.*?)>]=${1}
json.rule.convert[#regex:org.springframework.http.ResponseEntity]=java.lang.Object
###set resolveProperty = true

加载 spring-boot 相关配置:

properties

#Import spring properties
properties.additional=${module_path}/src/main/resources/application.properties
properties.additional=${module_path}/src/main/resources/application.yml
properties.additional=${module_path}/src/main/resources/application.yaml

默认使用 spring-boot 配置中的server.servlet.context-path

properties

#Resolve spring properties
###set ignoreUnresolved = true
class.prefix.path=${server.servlet.context-path}
###set ignoreUnresolved = false

Spring Boot Webflux

在推荐配置中有部分springboot-webflux相关的配置

properties

#resolve Mono/Flux
###set resolveProperty = false
json.rule.convert[#regex:reactor.core.publisher.Mono<(.*?)>]=${1}
json.rule.convert[#regex:reactor.core.publisher.Mono]=java.lang.Object
json.rule.convert[#regex:reactor.core.publisher.Flux<(.*?)>]=java.util.List<${1}>
json.rule.convert[#regex:reactor.core.publisher.Flux]=java.util.List<java.lang.Object>
###set resolveProperty = true

Swagger

默认推荐配置中不包含swagger的支持

如果需要支持swagger,可自行按需增加如下配置

基础配置

properties

# swagger

# ApiParam
param.doc=@io.swagger.annotations.ApiParam#value
param.default.value=@io.swagger.annotations.ApiParam#defaultValue
param.required=@io.swagger.annotations.ApiParam#required
param.ignore=@io.swagger.annotations.ApiParam#hidden

# Api
class.doc=@io.swagger.annotations.Api#value
class.doc=@io.swagger.annotations.Api#tags
ignore=@io.swagger.annotations.Api#hidden

# ApiModel
class.doc=@io.swagger.annotations.ApiModel#value
class.doc=@io.swagger.annotations.ApiModel#description

# ApiModelProperty
json.rule.field.name=@io.swagger.annotations.ApiModelProperty#name
field.ignore=@io.swagger.annotations.ApiModelProperty#hidden
field.doc=@io.swagger.annotations.ApiModelProperty#value
field.doc=@io.swagger.annotations.ApiModelProperty#notes
field.required=@io.swagger.annotations.ApiModelProperty#required

# ApiOperation
method.doc=@io.swagger.annotations.ApiOperation#value
api.tag=@io.swagger.annotations.ApiOperation#tags

快速配置

properties

properties.additional=https://cdn.apifox.cn/ide-plugin/idea/apifox-helper/setting/swagger.config

增强配置

可根据实际情况修改

properties


# swagger-advanced

# resolve the parameters from ApiImplicitParam
resolve_api_implicit_param=```
    def desc = map.value
    def allowableValues = map.allowableValues
    if(tool.notNullOrBlank(allowableValues)){
        desc = desc + "\n允许的值:" + allowableValues
    }

    def paramType = map.paramType ?: "query"
    def required = map.required?:true
    if(paramType==""||paramType=="query"){
        api.setParam(map.name,map.defaultValue,required,desc)
    }else if(paramType=="form"){
        api.setFormParam(map.name,map.defaultValue,required,desc)
    }else if(paramType=="path"){
        api.setPathParam(map.name,map.defaultValue,desc)
    }else if(paramType=="header"){
        api.setHeader(map.name,map.defaultValue,required,desc)
    }
```

# extract map from ApiImplicitParam
export.after[@io.swagger.annotations.ApiImplicitParam]=groovy:```
    def map = it.annMap("io.swagger.annotations.ApiImplicitParam")
    ${resolve_api_implicit_param}
```

# extract maps from ApiImplicitParams
export.after[@io.swagger.annotations.ApiImplicitParams]=groovy:```
    def maps = it.annMap("io.swagger.annotations.ApiImplicitParams")
    for(map in maps){
        ${resolve_api_implicit_param}
    }
```



# Resolve the response from `APIResponse` into the API description
resolve_api_response=```
    def desc = "\\n\\n***响应码***:"+map.code+"\\n\\n"
    desc += map.message+"\\n\\n"
    def response = map.response
    if(response!=null){
        def responseClass = helper.findClass(response)
        if(responseClass!=null){
            desc += "响应内容:\\n```json\\n" + responseClass.toJson(true) + "\\n```\\n"
        }
    }
    api.appendDesc(desc)
```


# Resolve `APIResponse` into the API description
export.after[@io.swagger.annotations.ApiResponse]=groovy:```
    def map = it.annMap("io.swagger.annotations.ApiResponse")
    ${resolve_api_response}
```

# Resolve `APIResponses` into the API description
export.after[@io.swagger.annotations.ApiResponses]=groovy:```
    def maps = it.annMap("io.swagger.annotations.ApiResponses")
    for(map in maps.value){
        ${resolve_api_response}
    }
```


# Resolve one `APIResponse` into the API description
export.after[@io.swagger.annotations.ApiResponse]=groovy:```
    def map = it.annMap("io.swagger.annotations.ApiResponse")

    api.setResponseCode(map.code?:200)
    api.appendResponseBodyDesc(map.message)
    def responseHeaders = map.responseHeaders
    if(responseHeaders!=null){
        for(responseHeader in responseHeaders) {
            api.setResponseHeader(responseHeader.name,"",true,responseHeader.description)
        }
    }
    def response = map.response
    if(response!=null){
        api.setResponseBodyClass(response)
    }
```

快速配置

properties

properties.additional=https://cdn.apifox.cn/ide-plugin/idea/apifox-helper/setting/swagger.advanced.config

JAX-RS

插件支持JAX-RS协议

确认勾选:Preferences(Settings) > Other Settings > EasyApi > Support > jaxrs(quarkus | jersey)

quarkus & jersey

jaxrs

javax.validation

在推荐配置中有部分 javax.validation 相关的简单配置

简单-不分组

默认选择的就是不分组模式javax.validation
可以在 Preferences(Settings) > Other Settings > EasyApi >Recommend 中检查是否有勾选javax.validation, 并移除勾选javax.validation(grouped)

简单-分组

默认选择的是不分组模式javax.validation
如果需要开启分组校验, 可以在 Preferences(Settings) > Other Settings > EasyApi >Recommend 中移除勾选javax.validation, 勾选javax.validation(grouped)

完全-不分组

需要对javax.validation完整的支持, 可自行增加如下配置

# rules for javax.validation

#Support for javax.validation annotations
param.required=@javax.validation.constraints.NotBlank
field.required=@javax.validation.constraints.NotBlank
param.required=@javax.validation.constraints.NotNull
field.required=@javax.validation.constraints.NotNull
param.required=@javax.validation.constraints.NotEmpty
field.required=@javax.validation.constraints.NotEmpty

# define var
number_min=-9999
number_max=9999
float_dmin=2
java_integer_types=["java.lang.Integer","int","java.lang.Long","long","java.lang.Short","short","java.math.BigInteger"]
java_float_types=["java.lang.String","java.lang.Float","float","java.lang.Double","double","java.math.BigDecimal"]
# mock_integer_or_float=${java_integer_types}.contains(it.type().name())?"@integer":"@float"

# AssertTrue|AssertFalse
field.mock[@javax.validation.constraints.AssertFalse]=false
field.demo[@javax.validation.constraints.AssertFalse]=false
field.mock[@javax.validation.constraints.AssertTrue]=true
field.demo[@javax.validation.constraints.AssertTrue]=true

# DecimalMax+DecimalMin -mock
field.mock[groovy:it.hasAnn("javax.validation.constraints.DecimalMax")&&it.hasAnn("javax.validation.constraints.DecimalMin")&&${java_integer_types}.contains(it.jsonType().name())]=groovy:"@integer("+it.ann("javax.validation.constraints.DecimalMin")+","+it.ann("javax.validation.constraints.DecimalMax")+")"
field.mock[groovy:it.hasAnn("javax.validation.constraints.DecimalMax")&&it.hasAnn("javax.validation.constraints.DecimalMin")&&${java_float_types}.contains(it.jsonType().name())]=groovy:"@float("+it.ann("javax.validation.constraints.DecimalMin")+","+it.ann("javax.validation.constraints.DecimalMax")+",${float_dmin})"

# DecimalMax|DecimalMin  -mock
field.mock[groovy:it.hasAnn("javax.validation.constraints.DecimalMax")&&${java_integer_types}.contains(it.jsonType().name())]=groovy:"@integer(0,"+it.ann("javax.validation.constraints.DecimalMax")+")"
field.mock[groovy:it.hasAnn("javax.validation.constraints.DecimalMin")&&${java_integer_types}.contains(it.jsonType().name())]=groovy:"@integer("+it.ann("javax.validation.constraints.DecimalMin")+")"
field.mock[groovy:it.hasAnn("javax.validation.constraints.DecimalMax")&&${java_float_types}.contains(it.jsonType().name())]=groovy:"@float(0,"+it.ann("javax.validation.constraints.DecimalMax")+",${float_dmin})"
field.mock[groovy:it.hasAnn("javax.validation.constraints.DecimalMin")&&${java_float_types}.contains(it.jsonType().name())]=groovy:"@float("+it.ann("javax.validation.constraints.DecimalMin")+",${number_max},${float_dmin})"

# DecimalMax、DecimalMin  -advanced
field.advanced[@javax.validation.constraints.DecimalMax]=groovy:```
    def ann = it.annMap("javax.validation.constraints.DecimalMax")
    return [maximum:ann["value"],exclusiveMaximum:(ann["inclusive"]==false)]
```
field.advanced[@javax.validation.constraints.DecimalMin]=groovy:```
    def ann = it.annMap("javax.validation.constraints.DecimalMin")
    return [minimum:ann["value"],exclusiveMinimum:(ann["inclusive"]==false)]
```

# javax.validation.constraints.Digits

field.mock[groovy:it.hasAnn("javax.validation.constraints.Digits")&&${java_integer_types}.contains(it.jsonType().name())]=groovy:```
    def max = "9".repeat(it.annValue("javax.validation.constraints.Digits","integer")).toInteger()
    return "@integer("+(-max)+","+max+")"
```
field.mock[groovy:it.hasAnn("javax.validation.constraints.Digits")&&${java_float_types}.contains(it.jsonType().name())]=groovy:```
    def max = ("9".repeat(it.annValue("javax.validation.constraints.Digits","integer"))+"."+"9".repeat(it.annValue("javax.validation.constraints.Digits","fraction"))).toDouble()
    return "@float("+(-max)+","+max+",0,"+it.ann("javax.validation.constraints.Digits","fraction")+")"
```

field.advanced[groovy:it.hasAnn("javax.validation.constraints.Digits")&&${java_integer_types}.contains(it.jsonType().name())]=groovy:```
    def max = "9".repeat(it.annValue("javax.validation.constraints.Digits","integer")).toInteger()
    return [minimum:-max,maximum:max]
```
field.advanced[groovy:it.hasAnn("javax.validation.constraints.Digits")&&${java_float_types}.contains(it.jsonType().name())]=groovy:```
    def max = ("9".repeat(it.annValue("javax.validation.constraints.Digits","integer"))+"."+"9".repeat(it.annValue("javax.validation.constraints.Digits","fraction"))).toDouble()
    return [minimum:-max,maximum:max]
```


# javax.validation.constraints.Email
field.mock[@javax.validation.constraints.Email]=groovy:"@email"
field.advanced[@javax.validation.constraints.Email]={"format":"email"}

# Max+Min
field.mock[groovy:it.hasAnn("javax.validation.constraints.Max")&&it.hasAnn("javax.validation.constraints.Min")&&${java_integer_types}.contains(it.jsonType().name())]=groovy:"@integer("+it.ann("javax.validation.constraints.Min")+","+it.ann("javax.validation.constraints.Max")+")"
field.mock[groovy:it.hasAnn("javax.validation.constraints.Max")&&it.hasAnn("javax.validation.constraints.Min")&&${java_float_types}.contains(it.jsonType().name())]=groovy:"@float("+it.ann("javax.validation.constraints.Min")+","+it.ann("javax.validation.constraints.Max")+",${float_dmin})"

# Max|Min
field.mock[groovy:it.hasAnn("javax.validation.constraints.Max")&&${java_integer_types}.contains(it.jsonType().name())]=groovy:"@integer(0,"+it.ann("javax.validation.constraints.Max")+")"
field.mock[groovy:it.hasAnn("javax.validation.constraints.Min")&&${java_integer_types}.contains(it.jsonType().name())]=groovy:"@integer("+it.ann("javax.validation.constraints.Min")+")"
field.mock[groovy:it.hasAnn("javax.validation.constraints.Max")&&${java_float_types}.contains(it.jsonType().name())]=groovy:"@float(0,"+it.ann("javax.validation.constraints.Max")+")"
field.mock[groovy:it.hasAnn("javax.validation.constraints.Min")&&${java_float_types}.contains(it.jsonType().name())]=groovy:"@float("+it.ann("javax.validation.constraints.Min")+",${number_max},${float_dmin})"

# Max、Min  -advanced
field.advanced[@javax.validation.constraints.Max]=groovy:```
    return [maximum:it.ann("javax.validation.constraints.Max")]
```
field.advanced[@javax.validation.constraints.Min]=groovy:```
    return [minimum:it.ann("javax.validation.constraints.Min")]
```

# Negative&NegativeOrZero
field.mock[groovy:it.hasAnn("javax.validation.constraints.Negative")&&${java_integer_types}.contains(it.jsonType().name())]=groovy:"@integer(${number_min},-1)"
field.mock[groovy:it.hasAnn("javax.validation.constraints.NegativeOrZero")&&${java_integer_types}.contains(it.jsonType().name())]=groovy:"@integer(${number_min},0)"
field.mock[groovy:it.hasAnn("javax.validation.constraints.Negative")&&${java_float_types}.contains(it.jsonType().name())]=groovy:"@float(${number_min},0.01,${float_dmin})"
field.mock[groovy:it.hasAnn("javax.validation.constraints.NegativeOrZero")&&${java_float_types}.contains(it.jsonType().name())]=groovy:"@float(${number_min},0,${float_dmin})"

field.advanced[groovy:it.hasAnn("javax.validation.constraints.Negative")&&${java_integer_types}.contains(it.jsonType().name())]={maximum:-1}
field.advanced[groovy:it.hasAnn("javax.validation.constraints.Negative")&&${java_float_types}.contains(it.jsonType().name())]={maximum:-0.001}
field.advanced[@javax.validation.constraints.NegativeOrZero]={"maximum":0}

# javax.validation.constraints.Pattern
field.advanced[@javax.validation.constraints.Pattern]=groovy:```
    return tool.toJson([pattern:it.ann("javax.validation.constraints.Pattern","regexp")])
```

# Positive&PositiveOrZero
field.mock[groovy:it.hasAnn("javax.validation.constraints.Positive")&&${java_integer_types}.contains(it.jsonType().name())]=groovy:"@integer(1,${number_max})"
field.mock[groovy:it.hasAnn("javax.validation.constraints.PositiveOrZero")&&${java_integer_types}.contains(it.jsonType().name())]=groovy:"@integer(0,${number_max})"
field.mock[groovy:it.hasAnn("javax.validation.constraints.Positive")&&${java_float_types}.contains(it.jsonType().name())]=groovy:"@float(0.01,${number_max},${float_dmin})"
field.mock[groovy:it.hasAnn("javax.validation.constraints.PositiveOrZero")&&${java_float_types}.contains(it.jsonType().name())]=groovy:"@float(0,${number_max},${float_dmin})"

field.advanced[groovy:it.hasAnn("javax.validation.constraints.Positive")&&${java_integer_types}.contains(it.jsonType().name())]={minimum:1}
field.advanced[groovy:it.hasAnn("javax.validation.constraints.Positive")&&${java_float_types}.contains(it.jsonType().name())]={minimum:0.001}
field.advanced[@javax.validation.constraints.PositiveOrZero]={minimum:0}

# javax.validation.constraints.Size

field.mock[groovy:it.hasAnn("javax.validation.constraints.Size")&&it.jsonType().name()=="java.lang.String"]=groovy:```
    def ann = it.annMap("javax.validation.constraints.Size")
    if(ann.containsKey("min")&&ann.containsKey("max")){
        return "@string("+ann["min"]+","+ann["max"]+")"
    }else if(ann.containsKey("min")){
        return "@string("+ann["min"]+")"
    }else if(ann.containsKey("max")){
        return "@string(0,"+ann["max"]+")"
    }
```
field.advanced[@javax.validation.constraints.Size]=groovy:```
    def element = (it.jsonType().name() == "java.lang.String")?"Length":"Items"
    def ann = it.annMap("javax.validation.constraints.Size")
    def advanced = [:]
    if(ann.containsKey("min")){
        advanced["min"+element] = ann["min"]
    }
    if(ann.containsKey("max")){
        advanced["max"+element] = ann["max"]
    }
    return advanced
```

上述配置可根据实际情况予以必要的调整

key	desc
number_min	数字最小值
number_max	数字最大值
float_dmin	浮点数小数位数

快速配置

properties.additional=https://cdn.apifox.cn/ide-plugin/idea/apifox-helper/setting/javax.validation.config

或者

properties.additional=https://gitee.com/tangcent/easy-yapi/raw/master/third/javax.validation.config

完全-分组

Jackson

JsonProperty&JsonIgnore

推荐配置中默认支持.

#Support for Jackson annotations
field.name=@com.fasterxml.jackson.annotation.JsonProperty#value
field.ignore=@com.fasterxml.jackson.annotation.JsonIgnore#value

JsonIgnoreProperties

推荐配置中有提供选项, 但默认未选中.


#Support for Jackson annotation JsonIgnoreProperties

json.cache.disable=true
field.ignore=groovy:it.containingClass().annValue("com.fasterxml.jackson.annotation.JsonIgnoreProperties")?.contains(it.name())
json.group=@com.fasterxml.jackson.annotation.JsonIgnoreProperties
field.parse.before[@com.fasterxml.jackson.annotation.JsonIgnoreProperties]=groovy:```
    def properties = it.annValue("com.fasterxml.jackson.annotation.JsonIgnoreProperties")
    for(property in properties){
        def path = fieldContext.property(property)
        session.set("json-ignore", path, true)
    }
```
field.parse.after[@com.fasterxml.jackson.annotation.JsonIgnoreProperties]=groovy:```
    def properties = it.annValue("com.fasterxml.jackson.annotation.JsonIgnoreProperties")
    for(property in properties){
        def path = fieldContext.property(property)
        session.remove("json-ignore", path)
    }
```
field.ignore=groovy:```
    return session.get("json-ignore", fieldContext.path())
```

Dubbo

如果仅希望导出markdown

参照导出普通 java method 文档即可

如果希望导出到Apifox

参照自定义框架

取消勾选 Preferences(Settings) > Other Settings > Apifox Helper > Support > methodDoc
勾选 Preferences(Settings) > Other Settings > Apifox Helper > Support > generic export
在 Preferences(Settings) > Other Settings > Apifox Helper > BuiltinConfig 或者本地文件引入配置:

properties.additional=https://cdn.apifox.cn/ide-plugin/idea/apifox-helper/setting/dubbo.config

如果配置不满足预期, 复制并修改dubbo.config的内容放在配置里, 替换掉上面的引入配置

前置操作/后置操作

导入的数据源

发布文档

脚本 API 参考

脚本示例

配置

进阶使用

框架支持

Spring Boot

Spring Boot Webflux

Swagger

基础配置

增强配置

JAX-RS

quarkus & jersey

javax.validation

简单-不分组

简单-分组

完全-不分组

完全-分组

Jackson

JsonProperty&JsonIgnore

JsonIgnoreProperties

Dubbo

框架支持 #

Spring Boot #

Spring Boot Webflux #

Swagger #

基础配置 #

增强配置 #

JAX-RS #

quarkus & jersey #

javax.validation #

简单-不分组 #

简单-分组 #

完全-不分组 #

完全-分组 #

Jackson #

JsonProperty&JsonIgnore #

JsonIgnoreProperties #

Dubbo #

框架支持

Spring Boot

Spring Boot Webflux

Swagger

基础配置

增强配置

JAX-RS

quarkus & jersey

javax.validation

简单-不分组

简单-分组

完全-不分组

完全-分组

Jackson

JsonProperty&JsonIgnore

JsonIgnoreProperties

Dubbo