此插件配置过于灵活, 以下均为示例, 需根据实际情况做合适的处理。
module
用于分类api
postman
时,每个module
将作为一个单独的文件夹yapi
时,每个module
需要配置相应的token
,即对应一个yapi
中的项目默认情况下取当前模块名(单模块项目取项目名)
默认推荐配置:
#find module from comment tag
module=#module
/**
* Mock Apis
*
* @module mock
*/
@RestController
@RequestMapping(value = "mock")
public class MockCtrl {
}
#ignore class or method which has comment tag 'ignore'
ignore=#ignore
/**
* Mock Apis
*
* @ignore
*/
@RestController
@RequestMapping(value = "mock")
public class MockCtrl {
}
/**
* Mock Apis
*/
@RestController
@RequestMapping(value = "mock")
public class MockCtrl {
/**
* Mock String
* @ignore
*/
@GetMapping("/string")
public String mockString() {
return Result.success("mock string");
}
}
一般来说:
/**
* 第一行注释作为文件夹的标题
* 剩余行注释作为文件夹的描述
*/
@RestController
@RequestMapping(value = "mock")
public class MockCtrl {
/**
* 第一行行注释作为API的标题
* 剩余行注释作为API的描述
*/
@GetMapping("/string")
public String mockString() {
return Result.success("mock string");
}
}
特殊需求参照:class.doc | method.doc | api.name
默认推荐配置如下:
method.doc[#deprecated]=groovy:"\n「deprecated」" + it.doc("deprecated")
method.doc[@java.lang.Deprecated]=「deprecated」
method.doc[@kotlin.Deprecated]=groovy:"\n「deprecated」" + it.ann("kotlin.Deprecated","message")
method.doc[groovy:it.containingClass().hasDoc("deprecated")]=groovy:"\n「deprecated」" + it.containingClass().doc("deprecated")
method.doc[groovy:it.containingClass().hasAnn("java.lang.Deprecated")]=「deprecated」
method.doc[groovy:it.containingClass().hasAnn("kotlin.Deprecated")]=groovy:"\n「deprecated」 " + it.containingClass().ann("kotlin.Deprecated","message")
使用注解或者注释标记API废弃即可:
/**
* 可以用注解`@Deprecated`来表示api废弃
* 也可以用注释`@deprecated`
*
* @deprecated 改用{@link #methodName3(String)}
*/
@Deprecated
@RequestMapping(value = "/pathOfApi2")
public Result methodName2(@RequestBody MockDtoOrVo jsonModel){
...
}
## security description
method.doc[@javax.annotation.security.RolesAllowed]=groovy:"require role:"+it.ann("javax.annotation.security.RolesAllowed")
/**
* 第一行注释作为文件夹的标题
* 剩余行注释作为文件夹的描述
*/
@RestController
@RequestMapping(value = "mock")
public class MockCtrl {
/**
* 第一行行注释作为API的标题
* 剩余行注释作为API的描述
*/
@GetMapping("/string")
@RolesAllowed("admin")
public String mockString() {
return Result.success("mock string");
}
}
## security description
doc.method[@org.springframework.security.access.prepost.PreAuthorize]=groovy:```
def preAuthorize = it.ann("org.springframework.security.access.prepost.PreAuthorize")
if(tool.nullOrBlank(preAuthorize)){
return
}
def role = regex.getGroup1("hasRole\\('(.*?)'\\)",preAuthorize)
return "require role: $role"
```
/**
* 第一行注释作为文件夹的标题
* 剩余行注释作为文件夹的描述
*/
@RestController
@RequestMapping(value = "mock")
public class MockCtrl {
/**
* 第一行行注释作为API的标题
* 剩余行注释作为API的描述
*/
@GetMapping("/string")
@PreAuthorize("hasRole('admin')")
public String mockString() {
return Result.success("mock string");
}
}
## ignore field 'log'
json.rule.field.ignore=log
## ignore field 'log' typed xxx.xxx.Log
json.rule.field.ignore=groovy:it.type().name()=="xxx.xxx.Log"
#ignore transient field
json.rule.field.ignore=groovy:it.hasModifier("transient")
java.time.LocalDateTime
作为yyyy-mm-dd
形式字符串处理#Resolve 'java.time.LocalDateTime' as 'java.lang.String'
json.rule.convert[java.time.LocalDateTime]=java.lang.String
json.rule.convert[java.time.LocalDate]=java.lang.String
java.time.LocalDateTime
作为timestamp
处理#Resolve 'java.time.LocalDateTime' as 'java.lang.Long'
json.rule.convert[java.time.LocalDateTime]=java.lang.Long
json.rule.convert[java.time.LocalDate]=java.lang.Long
配置如下:
method.doc[#result]=groovy: it.docs("result").collect{helper.resolveLink(it)}.grep{it!=null}.collect{"可能的返回:\n\n```json\n"+it.toJson(true)+"\n```\n\n"}.join("\n")
使用如下:
/**
* @result {@link UserInfo}
* @result {@link Result<UserInfo>}
*/
public Result mockString() {
...
}
配置如下:
field.doc[#maybe]=groovy:it.docs("maybe").collect{helper.resolveLink(it)}.collect{"可能是:\n\n```json\n" + it.toJson(true) +"\n```\n\n"}.join("\n")
使用如下:
/**
* @maybe {@link UserInfo}
* @maybe {@link java.lang.String}
*/
public Object target;
javax.validation
, 勾选javax.validation(grouped)
Jackson_JsonIgnoreProperties
com.xxx.Xxx is to complex. Blocked cause by xxx reached xxx
, 如何处理# ignore field with type com.xxx.Xxx
field.ignore=groovy:it.type().name()=="com.xxx.Xxx"
max.deep=8
max.elements=512