smart-doc-group

配置项

完整配置

配置	版本	必填	类型	默认值	描述
outPath		✔	String		指定文档的输出路径
serverUrl		❌	String	http://127.0.0.1	服务器地址, 导出postman建议设置成http://方便直接在postman直接设置环境变量。 2.4.8后导出postman建议使用serverEnv,避免多出导出时修改配置。
serverEnv	2.4.8	❌	String		服务器地址, 导出postman建议设置成http://方便直接在postman直接设置环境变量。改配置是为了支持postman导出时不用全局修改serverUrl
pathPrefix	2.2.3	❌	String		设置path前缀, 如配置Servlet ContextPath。
isStrict		❌	Boolean		是否开启严格模式,严格模式会强制检查代码注释，在2.6.3即以后的插件版本设置此项时检查到注释错误也会直接中断插件白嵌套的构建周期。 作为团队使用建议使用设置为true，提升对开发人员的注释要求，提升文档的完善度。
allInOne		❌	Boolean	false	是否将文档合并到一个文件中，一般推荐为true。
coverOld		❌	Boolean	false	是否覆盖旧的文件，主要用于Markdown文件覆盖。
createDebugPage	2.0.1	❌	Boolean	false	smart-doc支持创一个类似Swagger那种可调试接口的HTML文档页面，仅在AllInOne模式中起作用。 从@2.0.1开始，对html文档，无论是allInOne还是非allInOne模式都能够生成debug页面。
packageFilters		❌	String		Controller包过滤，多个包用英文逗号隔开。 2.2.2开始需要采用正则：com.test.controller.* 2.7.1开始支持方法级别正则：com.test.controller.TestController.*
packageExcludeFilters		❌	String		对packageFilters排除子包，多个包用英文逗号隔开 2.2.2开始需要采用正则：com.test.controller.res.*
md5EncryptedHtmlName		❌	Boolean	false	只有每个Controller生成一个HTML文件是才使用。
style		❌	String		基于highlight.js的代码高亮设置。
projectName		❌	String		只有每个Controller生成一个HTML文件是才使用。 如果smart-doc.json中和插件中都未设置projectName，2.3.4开始，插件自动采用pom中的projectName作为默认填充， 因此使用插件时可以不配置。
skipTransientField	1.7.8	❌	Boolean	true	自 3.0.8 起已弃用。请使用 serializeRequestTransients 和 serializeResponseTransients 代替。此配置用于跳过请求和响应体中瞬态字段的序列化。
serializeRequestTransients	3.0.8	❌	Boolean	false	决定是否序列化请求对象中的瞬态字段。设置为 true 时，transient修饰的字段将包含在请求序列化中。
serializeResponseTransients	3.0.8	❌	Boolean	false	决定是否序列化响应对象中的瞬态字段。设置为 true 时，transient修饰的字段将包含在响应序列化中。
sortByTitle	1.8.7	❌	Boolean	false	接口标题排序。
showAuthor		❌	Boolean	true	是否显示接口作者名称。
requestFieldToUnderline	1.8.7	❌	Boolean	false	自动将驼峰入参字段在文档中转为下划线格式。
responseFieldToUnderline	1.8.7	❌	Boolean	false	自动将驼峰响应字段在文档中转为下划线格式。
inlineEnum	1.8.8	❌	Boolean	false	是否将枚举详情展示到参数表中。
recursionLimit	1.8.8	❌	int	7	设置允许递归执行的次数用于避免一些对象解析卡主。
allInOneDocFileName	1.9.0	❌	String	index.html	只有配置项目所有Controller生成一个HTML文件时才生效。
requestExample	1.9.0	❌	Boolean	true	是否将请求示例展示在文档中。
responseExample	1.9.0	❌	Boolean	true	是否将响应示例展示在文档中。
urlSuffix	2.1.0	❌	String		支持SpringMVC旧项目的url后缀。
language		❌	String	CHINESE	mock值的国际化支持。
displayActualType	1.9.6	❌	Boolean	false	是否在注释栏自动显示泛型的真实类型短类名。
appKey	2.0.9	❌	String		torna平台对接appKey。
appToken	2.0.9	❌	String		torna平台appToken。
secret	2.0.9	❌	String		torna平台secret。
openUrl	2.0.9	❌	String		torna平台地址，填写自己的私有化部署地址。
debugEnvName		❌	String		torna环境名称。
replace	2.2.4	❌	Boolean	true	推送torna时替换旧的文档。改动还是会推送过去覆盖的，这个功能主要是保证代码删除了，torna上没有删除。
debugEnvUrl	2.0.9	❌	String		推送torna配置接口服务地址。
tornaDebug	2.0.9	❌	Boolean	true	是否打印torna推送日志。
author	2.0.9	❌	String		指定推送到Torna的用户名
ignoreRequestParams	1.9.2	❌	List<String>		忽略请求参数对象，把不想生成文档的参数对象屏蔽掉。
dataDictionaries		❌	List<Object>		配置数据字典 2.4.6开始可以配置枚举实现的接口， 当配置接口时title将使用实现枚举的类描述，如果有已经实现的枚举需要忽略的话，可以在实现枚举类上增加@ignore进行忽略。
errorCodeDictionaries		❌	List<Object>		错误码列表 2.4.6开始可以配置枚举实现的接口， 当配置接口时title将使用实现枚举的类描述，如果有已经实现的枚举需要忽略的话，可以在实现枚举类上增加@ignore进行忽略。
revisionLogs		❌	List<Object>		文档变更记录。
customResponseFields		❌	List<Object>		自定义添加字段和注释，一般用户处理第三方jar包库。
customRequestFields		❌	List<Object>		自定义请求体的注释。
requestHeaders	2.1.3	❌	List<Object>		设置公共请求头。
requestParams	2.2.3	❌	List<Object>		公共请求参数(通过拦截器处理的场景)。
rpcApiDependencies		❌	List<Object>		项目开放的Dubbo API接口模块依赖，配置后输出到文档方便使用者集成。
rpcConsumerConfig		❌	String		文档中添加Dubbo Consumer集成配置，用于方便集成方可以快速集成。
apiObjectReplacements	1.8.5	❌	List<Object>		使用自定义类覆盖其他类做文档渲染。
apiConstants	1.8.9	❌	List<Object>		配置自己的常量类，smart-doc在解析到常量时自动替换为具体的值。 2.4.2版本开始使用到常量也无需配置，smart-doc已经能够自动解析。
responseBodyAdvice	1.8.9	❌	List<Object>		ResponseBodyAdvice是Spring框架中预留的钩子，它作用在Controller方法执行完成之后，http响应体写回客户端之前， 它能方便的织入一些自己的业务逻辑处理了，因此smart-doc也提供了对ResponseBodyAdvice统一返回设置(不要随便配置根据项目的技术来配置)支持， 可用ignoreResponseBodyAdvice tag来忽略。
requestBodyAdvice	2.1.4	❌	List<Object>		设置RequestBodyAdvice统一请求包装类。
groups	2.2.5	❌	List<Object>		对不同的Controller进行分组。
requestParamsTable	2.2.5	❌	String		是否将请求参数表展示在文档中。
responseParamsTable	2.2.5	❌	Boolean		是否将响应参数表展示在文档中。
framework	2.2.5	❌	String	spring or dubbo	Spring和Apache Dubbo是smart-doc默认支持解析生成文档的框架，不配置framework时根据触发的文档构建场景自动选择Spring或者 Dubbo，smart-doc目前也支持JAX-RS的标准，因此使用支持JAX-RS标准的框架(如：Quarkus)可以作为体验使用，但是还不完善。 可选值: spring,dubbo,JAX-RS,solon
randomMock	2.6.9	❌	Boolean	false	randomMock用于控制是否让smart-doc生成随机mock值，在2.6.9之前的版本中smart-doc会自动给参数和自动生成随机值， 每次生成的值都不一样，现在你可以设置为false来控制随机值的生成。
componentType	2.7.8	❌	String	RANDOM	openapi component key generator RANDOM : 支持 @Validated 分组校验 NORMAL: 不支持 @Validated, 用于 openapi 生成代码
increment	3.0.0	❌	Boolean	false	increment用于控制是否让smart-doc根据GIT代码的变更实现文档的增量推送
apiUploadNums	3.0.2	❌	Integer		上传torna时，支持文档分批上传，设置文档批次的大小。不配置则一次上传所有
showValidation	3.0.3	❌	Boolean	true	showValidation用于控制smart-doc是否提取JSR字段验证信息展示到文档中
jmeter	3.0.4	❌	Object		生成JMeter性能测试脚本一些配置。
addDefaultHttpStatuses	3.0.5	❌	Boolean	false	生成文档时是否添加框架默认的http状态码，例如Spring MVC默认的500和404, 当前只有生成OenAPI文档时支持。

{
    "serverUrl": "http://127.0.0.1",
    "serverEnv": "http://",
    "pathPrefix": "",
    "isStrict": false,
    "allInOne": true,
    "outPath": "D://md2",
    "randomMock": false,
    "coverOld": true,
    "createDebugPage": true,
    "packageFilters": "",
    "packageExcludeFilters": "",
    "md5EncryptedHtmlName": false,
    "style": "xt256",
    "projectName": "smart-doc",
    "framework": "spring",
    "skipTransientField": true,
    "serializeRequestTransients": false,
    "serializeResponseTransients": false,
    "sortByTitle": false,
    "showAuthor": true,
    "requestFieldToUnderline": true,
    "responseFieldToUnderline": true,
    "inlineEnum": true,
    "recursionLimit": 7,
    "allInOneDocFileName": "index.html",
    "requestExample": "true",
    "responseExample": "true",
    "requestParamsTable": true,
    "responseParamsTable": true,
    "urlSuffix": ".do",
    "displayActualType": false,
    "appToken": "c16931fa6590483fb7a4e85340fcbfef",
    "isReplace": true,
    "openUrl": "http://localhost:7700/api",
    "debugEnvName": "Test ENV",
    "debugEnvUrl": "http://127.0.0.1",
    "tornaDebug": false,
    "author": "smart-doc",
    "increment": false,
    "ignoreRequestParams": [
        "org.springframework.ui.ModelMap"
    ],
    "dataDictionaries": [
        {
            "title": "http status",
            "enumClassName": "com.power.common.enums.HttpCodeEnum",
            "codeField": "code",
            "descField": "message"
        },
        {
            "enumClassName": "com.xx.IEnum",
            "codeField": "code",
            "descField": "message"
        }
    ],
    "errorCodeDictionaries": [
        {
            "title": "title",
            "enumClassName": "com.power.common.enums.HttpCodeEnum",
            "codeField": "code",
            "descField": "message",
            "valuesResolverClass": ""
        },
        {
            "enumClassName": "com.xx.IEnum",
            "codeField": "code",
            "descField": "message"
        }
    ],
    "revisionLogs": [
        {
            "version": "1.0",
            "revisionTime": "2020-12-31 10:30",
            "status": "update",
            "author": "author",
            "remarks": "desc"
        }
    ],
    "customResponseFields": [
        {
            "name": "code",
            "desc": "response code",
            "ownerClassName": "org.springframework.data.domain.Pageable",
            "ignore": true,
            "value": "00000"
        }
    ],
    "customRequestFields": [
        {
            "name": "code",
            "desc": "status code",
            "ownerClassName": "com.xxx.constant.entity.Result",
            "value": "200",
            "required": true,
            "ignore": false
        }
    ],
    "requestHeaders": [
        {
            "name": "token",
            "type": "string",
            "desc": "desc",
            "value": "token value",
            "required": false,
            "since": "-",
            "pathPatterns": "/app/test/**",
            "excludePathPatterns": "/app/page/**"
        },
        {
            "name": "appkey",
            "type": "string",
            "desc": "desc",
            "value": "appkey value",
            "required": false,
            "pathPatterns": "/test/add,/testConstants/1.0",
            "since": "-"
        }
    ],
    "requestParams": [
        {
            "name": "configPathParam",
            "type": "string",
            "desc": "desc",
            "paramIn": "path",
            "value": "testPath",
            "required": false,
            "since": "-",
            "pathPatterns": "**",
            "excludePathPatterns": "/app/page/**"
        },
        {
            "name": "configQueryParam",
            "type": "string",
            "desc": "desc",
            "paramIn": "query",
            "value": "testQuery",
            "required": false,
            "since": "-",
            "pathPatterns": "**",
            "excludePathPatterns": "/app/page/**"
        }
    ],
    "rpcApiDependencies": [
        {
            "artifactId": "SpringBoot2-Dubbo-Api",
            "groupId": "com.demo",
            "version": "1.0.0"
        }
    ],
    "rpcConsumerConfig": "src/main/resources/consumer-example.conf",
    "apiObjectReplacements": [
        {
            "className": "org.springframework.data.domain.Pageable",
            "replacementClassName": "com.power.doc.model.PageRequestDto"
        }
    ],
    "apiConstants": [
        {
            "constantsClassName": "com.power.doc.constants.RequestParamConstant"
        }
    ],
    "responseBodyAdvice": {
        "className": "com.power.common.model.CommonResult"
    },
    "requestBodyAdvice": {
        "className": "com.power.common.model.CommonResult"
    },
    "groups": [
        {
            "name": "test group",
            "apis": "com.power.doc.controller.app.*"
        }
    ],
    "requestParamsTable": true,
    "responseParamsTable": true,
    "componentType": "RANDOM",
    "jmeter": {
        "addPrometheusListener": true
    },
    "addDefaultHttpStatuses": true
}

packageFilters

Controller包过滤，多个包用英文逗号隔开。

PS: 2.2.2开始需要采用正则：com.test.controller.* ，2.7.1开始支持方法级别正则：com.test.controller.TestController.*

{
    "packageFilters": "com.test.controller.*", // 输出 controller 包下所有的接口
    "packageFilters": "com.example.controller.PetController", // 只输出 PetController 的接口
    "packageFilters": "com.example.controller.*Controller", // 输出 controller 包下以 Controller 后缀为类名的所有接口
    "packageFilters": "com.example.controller.Pet.*", // 输出 controller 包下以 Pet 开头为类名的所有接口
    "packageFilters": "com.example.controller.Pet.*Controller", // 输出 controller 包下符合 Pet*Controller 类名的所有接口
    "packageFilters": "com.example.controller.PetController.getPetInfo", // 输出 PetController 中 getPetInfo 方法接口
    "packageFilters": "com.example.controller.PetController.*", // 输出 PetController 中所有的接口
    "packageFilters": "com.example.controller.PetController.get.*", // 只输出 PetController 类中以 get 为方法名开头的所有接口
    "packageFilters": "com.example.controller.PetController.*Info", // 只输出 PetController 类中以 Info 为方法名结尾的所有接口
    "packageFilters": "com.example.controller.PetController.get.*Info", // 只输出 PetController 类中符合 get.*Info 为方法名的所有接口
}

dataDictionaries

配置数据字典，2.4.6开始可以配置枚举实现的接口， 当配置接口时title将使用实现枚举的类描述，如果有已经实现的枚举需要忽略的话，可以在实现枚举类上增加@ignore进行忽略。

配置	类型	描述
title	String
enumClassName	String	错误码枚举类
codeField	String	错误码的code码字段名称，smart-doc默认以getCode方法名去反射获取。如果没有get方法可以配置字段对应方法名，例如：code()。
descField	String	错误码的描述信息对应的字段名，和codeField一样可以配置为方法名,例如：message()

{
    "dataDictionaries": [
        {
            "title": "title",
            "enumClassName": "com.power.common.enums.HttpCodeEnum", 
            "codeField": "code", 
            "descField": "message" 
        }
    ]
}

errorCodeDictionaries

错误码列表，2.4.6开始可以配置枚举实现的接口， 当配置接口时title将使用实现枚举的类描述，如果有已经实现的枚举需要忽略的话，可以在实现枚举类上增加@ignore进行忽略。

配置	类型	描述
title	String
enumClassName	String	错误码枚举类
codeField	String	错误码的code码字段名称，smart-doc默认以getCode方法名去反射获取。如果没有get方法可以配置字段对应方法名，例如：code()。
descField	String	错误码的描述信息对应的字段名，和codeField一样可以配置为方法名,例如：message()

{
    "errorCodeDictionaries": [
        {
            "title": "title",
            "enumClassName": "com.power.common.enums.HttpCodeEnum", 
            "codeField": "code", 
            "descField": "message" 
        }
    ]
}

revisionLogs

文档变更记录。

配置	类型	描述
version	String	文档版本号
revisionTime	String	文档修订时间
status	String	变更操作状态，一般为：创建、更新等
author	String	文档变更作者
remarks	String	变更描述

{
    "revisionLogs": [
        {
            "version": "1.0", 
            "revisionTime": "2020-12-31 10:30", 
            "status": "update", 
            "author": "author", 
            "remarks": "desc" 
        }
    ]
}

customResponseFields

自定义添加字段和注释，一般用户处理第三方jar包库。

配置	类型	描述
name	String	覆盖响应码字段
desc	String	覆盖响应码的字段注释
ownerClassName	String	指定你要添加注释的类名
ignore	Boolean	设置true会被自动忽略掉不会出现在文档中
value	String	设置响应码的值

{
    "customResponseFields": [
        {
            "name": "code", 
            "desc": "响应代码", 
            "ownerClassName": "org.springframework.data.domain.Pageable",
            "ignore": true, 
            "value": "00000" 
        }
    ]
}

customRequestFields

自定义添加字段和注释，一般用户处理第三方jar包库。

配置	类型	描述
name	String	属性名
desc	String	描述
ownerClassName	String	属性对应的类全路径
ignore	Boolean	是否忽略
required	Boolean	是否必填
value	String	默认值或者mock值

{
    "customRequestFields": [
        {
            "name": "code", 
            "desc": "状态码", 
            "ownerClassName": "com.xxx.constant.entity.Result",
            "value": "200", 
            "required": true, 
            "ignore": false 
        }
    ]
}

rpcApiDependencies

项目开放的Dubbo API接口模块依赖，配置后输出到文档方便使用者集成。

配置	类型	描述
artifactId	String	artifactId
groupId	String	groupId
version	String	版本号

{
    "rpcApiDependencies": [
        {
            "artifactId": "SpringBoot2-Dubbo-Api",
            "groupId": "com.demo",
            "version": "1.0.0"
        }
    ]
}

apiObjectReplacements

使用自定义类覆盖其他类做文档渲染。

配置	类型	描述
className	String	需要被替换的全类名
replacementClassName	String	用于被替换的全类名

{
    "apiObjectReplacements": [
        {
            "className": "org.springframework.data.domain.Pageable",
            "replacementClassName": "com.power.doc.model.PageRequestDto" //自定义的PageRequestDto替换Pageable做文档渲染
        }
    ]
}

responseBodyAdvice

ResponseBodyAdvice是Spring框架中预留的钩子，它作用在Controller方法执行完成之后，http响应体写回客户端之前， 它能方便的织入一些自己的业务逻辑处理了，因此smart-doc也提供了对ResponseBodyAdvice统一返回设置(不要随便配置根据项目的技术来配置)支持， 可用ignoreResponseBodyAdvice tag来忽略。

配置	类型	描述
className	String	通用响应体

{
    "responseBodyAdvice": {
        "className": "com.power.common.model.CommonResult" 
    }
}

requestBodyAdvice

设置RequestBodyAdvice统一请求包装类。

配置	类型	描述
className	String	通用请求体

{
    "requestBodyAdvice": {
        "className": "com.power.common.model.CommonResult" 
    }
}

groups

对不同的Controller进行分组。

PS: 分组不对postman.json和openApi.json生效

配置	类型	描述
name	String	分组名称
apis	String	分组url, 支持正则 ，多个值用英文逗号隔开

{
    "groups": [
        {
            "name": "测试分组",
            "apis": "com.example.controller.*",
            "apis": "com.example.controller.PetController", // 只包含 PetController 的接口
            "apis": "com.example.controller.*Controller", // 包含controller 包下以 Controller 后缀为类名的所有接口
            "apis": "com.example.controller.Pet.*", // 包含 controller 包下以 Pet 开头为类名的所有接口
            "apis": "com.example.controller.Pet.*Controller" // 包含 controller 包下符合 Pet*Controller 类名的所有接口
        }
    ]
}

apis如果配置后在支持分组的模版上不生效，可能是正则配置有问题。可以自行调用smart-doc中DocUtil工具验证。 验证例子参考如下：

@Test
public void testIsMatch() {
    String pattern = "com.aaa.*.controller";
    String controllerName = "com.aaa.cc.controlle";
    System.out.println(DocUtil.isMatch(pattern, controllerName));
}

jmeter

3.0.4版本开始增加，生成JMeter性能测试脚本时的自定义配置项

配置	类型	描述
addPrometheusListener	Boolean	生成脚本时是否添加Prometheus监听器

{
  "jmeter": {
    "addPrometheusListener": true
  }
}

This site is open source. Improve this page.