diff --git a/README.md b/README.md index 1f7a6b9..964a1a5 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ # 版本基础 - Spring Boot：1.5.x -- Swagger：2.7.x +- Swagger：2.8.x # 如何使用 @@ -24,15 +24,17 @@ - 在`pom.xml`中引入依赖： +> 当前最新版本 1.7.0.RELEASE + ```xml com.spring4all swagger-spring-boot-starter - 1.6.0.RELEASE + 1.7.0.RELEASE ``` -**注意：从`1.6.0`开始，我们按Spring Boot官方建议修改了artifactId为`swagger-spring-boot-starter`，1.6.0之前的版本不做修改，依然为使用`spring-boot-starter-swagger` !** +**注意：从`1.6.1`开始，我们按Spring Boot官方建议修改了artifactId为`swagger-spring-boot-starter`，1.6.0之前的版本不做修改，依然为使用`spring-boot-starter-swagger` !** - 在应用主类中增加`@EnableSwagger2Doc`注解 @@ -249,13 +251,102 @@ swagger.ui-config.submit-methods=get,delete swagger.ui-config.submit-methods= ``` +--- + +### 来自2018年的版本升级，欢呼吧，Coder们 + +> 2018-03-21 今日春分，细雨如风 `1.7.0` 版本诞生 @gumutianqi + +#### UI升级到 2.8.0 版本 (1.7.0 + 支持) + +- 扁平化设计 +- 更加华丽 +- 更加易用 +- 可配置项更加自由 + + +### Authorization 鉴权配置 (1.7.0 + 支持) + +- 新增 Authorization 配置项 + +```properties +# 鉴权策略ID，对应 SecurityReferences ID +swagger.authorization.name=Authorization + +# 鉴权传递的Header参数 +swagger.authorization.key-name=token + +# 需要开启鉴权URL的正则, 默认^.*$匹配所有URL +swagger.authorization.auth-regex=^.*$ +``` + +备注：目前支持`ApiKey`鉴权模式，后续添加`Oauth2`和`BasicAuth`支持 + +##### 使用须知 + +> 1. 默认已经在全局开启了`global`的SecurityReferences，无需配置任何参数就可以使用； +> 2. 全局鉴权的范围在可以通过以上参数`auth-regex`进行正则表达式匹配控制； +> 3. 除了全局开启外，还可以手动通过注解在RestController上进行定义鉴权，使用方式如下： + +```java +// 其中的ID Authorization 即为配置项 swagger.authorization.name，详细请关注后面的配置代码 +@ApiOperation(value = "Hello World", authorizations = {@Authorization(value = "Authorization")}) +@RequestMapping(value = "/hello", method = RequestMethod.GET) +String hello(); +``` + +##### 关于如何配置实现鉴权，请关注以下code： + +```java +/** + * 配置基于 ApiKey 的鉴权对象 + * + * @return + */ +private ApiKey apiKey() { + return new ApiKey(swaggerProperties().getAuthorization().getName(), + swaggerProperties().getAuthorization().getKeyName(), + ApiKeyVehicle.HEADER.getValue()); +} + +/** + * 配置默认的全局鉴权策略的开关，以及通过正则表达式进行匹配；默认 ^.*$ 匹配所有URL + * 其中 securityReferences 为配置启用的鉴权策略 + * + * @return + */ +private SecurityContext securityContext() { + return SecurityContext.builder() + .securityReferences(defaultAuth()) + .forPaths(PathSelectors.regex(swaggerProperties().getAuthorization().getAuthRegex())) + .build(); +} + +/** + * 配置默认的全局鉴权策略；其中返回的 SecurityReference 中，reference 即为ApiKey对象里面的name，保持一致才能开启全局鉴权 + * + * @return + */ +private List defaultAuth() { + AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything"); + AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; + authorizationScopes[0] = authorizationScope; + return Collections.singletonList(SecurityReference.builder() + .reference(swaggerProperties().getAuthorization().getName()) + .scopes(authorizationScopes).build()); +} +``` + + - 其他配置 ```properties # json编辑器 swagger.ui-config.json-editor=false + # 显示请求头 swagger.ui-config.show-request-headers=true + # 页面调试请求的超时时间 swagger.ui-config.request-timeout=5000 ``` @@ -281,3 +372,4 @@ swagger.docket.aaa.ignored-parameter-types[1]=com.didispace.demo.Product - [程序猿DD-翟永超](https://github.com/dyc87112/) - [小火](https://renlulu.github.io/) - [泥瓦匠BYSocket](https://github.com/JeffLi1993) +- [LarryKoo-古拉里](https://github.com/gumutianqi) diff --git a/pom.xml b/pom.xml index 919934d..2a249ca 100644 --- a/pom.xml +++ b/pom.xml @@ -6,7 +6,7 @@ com.spring4all swagger-spring-boot-starter - 1.6.0.RELEASE + 1.7.0.RELEASE spring-boot-starter-swagger https://github.com/SpringForAll/spring-boot-starter-swagger @@ -48,8 +48,9 @@ UTF-8 1.8 - 2.7.0 - 1.5.6.RELEASE + 2.8.0 + 1.5.10.RELEASE + 1.16.18 @@ -81,7 +82,7 @@ org.projectlombok lombok - 1.16.12 + ${version.lombok} provided diff --git a/src/main/java/com/spring4all/swagger/SwaggerAutoConfiguration.java b/src/main/java/com/spring4all/swagger/SwaggerAutoConfiguration.java index c042126..143dd4e 100644 --- a/src/main/java/com/spring4all/swagger/SwaggerAutoConfiguration.java +++ b/src/main/java/com/spring4all/swagger/SwaggerAutoConfiguration.java @@ -2,7 +2,6 @@ import com.google.common.base.Predicate; import com.google.common.base.Predicates; -import com.google.common.collect.Lists; import org.springframework.beans.BeansException; import org.springframework.beans.factory.BeanFactory; import org.springframework.beans.factory.BeanFactoryAware; @@ -17,17 +16,19 @@ import org.springframework.web.bind.annotation.RequestMethod; import springfox.documentation.builders.*; import springfox.documentation.schema.ModelRef; -import springfox.documentation.service.ApiInfo; -import springfox.documentation.service.Contact; -import springfox.documentation.service.Parameter; -import springfox.documentation.service.ResponseMessage; +import springfox.documentation.service.*; import springfox.documentation.spi.DocumentationType; +import springfox.documentation.spi.service.contexts.SecurityContext; import springfox.documentation.spring.web.plugins.Docket; +import springfox.documentation.swagger.web.ApiKeyVehicle; import springfox.documentation.swagger.web.UiConfiguration; +import springfox.documentation.swagger.web.UiConfigurationBuilder; import java.util.*; import java.util.stream.Collectors; +import static com.google.common.collect.Lists.newArrayList; + /** * @author 翟永超 * Create date：2017/8/7. @@ -49,15 +50,20 @@ public SwaggerProperties swaggerProperties() { @Bean public UiConfiguration uiConfiguration(SwaggerProperties swaggerProperties) { - return new UiConfiguration( - swaggerProperties.getUiConfig().getValidatorUrl(),// url - swaggerProperties.getUiConfig().getDocExpansion(), // docExpansion => none | list - swaggerProperties.getUiConfig().getApiSorter(), // apiSorter => alpha - swaggerProperties.getUiConfig().getDefaultModelRendering(), // defaultModelRendering => schema - swaggerProperties.getUiConfig().getSubmitMethods().split(","), - swaggerProperties.getUiConfig().getJsonEditor(), // enableJsonEditor => true | false - swaggerProperties.getUiConfig().getShowRequestHeaders(), // showRequestHeaders => true | false - swaggerProperties.getUiConfig().getRequestTimeout()); // requestTimeout => in milliseconds, defaults to null (uses jquery xh timeout) + return UiConfigurationBuilder.builder() + .deepLinking(swaggerProperties.getUiConfig().getDeepLinking()) + .defaultModelExpandDepth(swaggerProperties.getUiConfig().getDefaultModelExpandDepth()) + .defaultModelRendering(swaggerProperties.getUiConfig().getDefaultModelRendering()) + .defaultModelsExpandDepth(swaggerProperties.getUiConfig().getDefaultModelsExpandDepth()) + .displayOperationId(swaggerProperties.getUiConfig().getDisplayOperationId()) + .displayRequestDuration(swaggerProperties.getUiConfig().getDisplayRequestDuration()) + .docExpansion(swaggerProperties.getUiConfig().getDocExpansion()) + .maxDisplayedTags(swaggerProperties.getUiConfig().getMaxDisplayedTags()) + .operationsSorter(swaggerProperties.getUiConfig().getOperationsSorter()) + .showExtensions(swaggerProperties.getUiConfig().getShowExtensions()) + .tagsSorter(swaggerProperties.getUiConfig().getTagsSorter()) + .validatorUrl(swaggerProperties.getUiConfig().getValidatorUrl()) + .build(); } @Bean @@ -93,7 +99,7 @@ public List createRestApi(SwaggerProperties swaggerProperties) { } // exclude-path处理 - List> excludePath = new ArrayList(); + List> excludePath = new ArrayList<>(); for (String path : swaggerProperties.getExcludePath()) { excludePath.add(PathSelectors.ant(path)); } @@ -101,6 +107,8 @@ public List createRestApi(SwaggerProperties swaggerProperties) { Docket docketForBuilder = new Docket(DocumentationType.SWAGGER_2) .host(swaggerProperties.getHost()) .apiInfo(apiInfo) + .securitySchemes(Collections.singletonList(apiKey())) + .securityContexts(Collections.singletonList(securityContext())) .globalOperationParameters(buildGlobalOperationParametersFromSwaggerProperties( swaggerProperties.getGlobalOperationParameters())); @@ -118,9 +126,9 @@ public List createRestApi(SwaggerProperties swaggerProperties) { ) ).build(); - /** ignoredParameterTypes **/ - Class[] array = new Class[swaggerProperties.getIgnoredParameterTypes().size()]; - Class[] ignoredParameterTypes = swaggerProperties.getIgnoredParameterTypes().toArray(array); + /* ignoredParameterTypes **/ + Class[] array = new Class[swaggerProperties.getIgnoredParameterTypes().size()]; + Class[] ignoredParameterTypes = swaggerProperties.getIgnoredParameterTypes().toArray(array); docket.ignoredParameterTypes(ignoredParameterTypes); configurableBeanFactory.registerSingleton("defaultDocket", docket); @@ -167,6 +175,8 @@ public List createRestApi(SwaggerProperties swaggerProperties) { Docket docketForBuilder = new Docket(DocumentationType.SWAGGER_2) .host(swaggerProperties.getHost()) .apiInfo(apiInfo) + .securitySchemes(Collections.singletonList(apiKey())) + .securityContexts(Collections.singletonList(securityContext())) .globalOperationParameters(assemblyGlobalOperationParameters(swaggerProperties.getGlobalOperationParameters(), docketInfo.getGlobalOperationParameters())); @@ -186,9 +196,9 @@ public List createRestApi(SwaggerProperties swaggerProperties) { ) .build(); - /** ignoredParameterTypes **/ - Class[] array = new Class[docketInfo.getIgnoredParameterTypes().size()]; - Class[] ignoredParameterTypes = docketInfo.getIgnoredParameterTypes().toArray(array); + /* ignoredParameterTypes **/ + Class[] array = new Class[docketInfo.getIgnoredParameterTypes().size()]; + Class[] ignoredParameterTypes = docketInfo.getIgnoredParameterTypes().toArray(array); docket.ignoredParameterTypes(ignoredParameterTypes); configurableBeanFactory.registerSingleton(groupName, docket); @@ -197,6 +207,44 @@ public List createRestApi(SwaggerProperties swaggerProperties) { return docketList; } + /** + * 配置基于 ApiKey 的鉴权对象 + * + * @return + */ + private ApiKey apiKey() { + return new ApiKey(swaggerProperties().getAuthorization().getName(), + swaggerProperties().getAuthorization().getKeyName(), + ApiKeyVehicle.HEADER.getValue()); + } + + /** + * 配置默认的全局鉴权策略的开关，以及通过正则表达式进行匹配；默认 ^.*$ 匹配所有URL + * 其中 securityReferences 为配置启用的鉴权策略 + * + * @return + */ + private SecurityContext securityContext() { + return SecurityContext.builder() + .securityReferences(defaultAuth()) + .forPaths(PathSelectors.regex(swaggerProperties().getAuthorization().getAuthRegex())) + .build(); + } + + /** + * 配置默认的全局鉴权策略；其中返回的 SecurityReference 中，reference 即为ApiKey对象里面的name，保持一致才能开启全局鉴权 + * + * @return + */ + private List defaultAuth() { + AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything"); + AuthorizationScope[] authorizationScopes = new AuthorizationScope[1]; + authorizationScopes[0] = authorizationScope; + return Collections.singletonList(SecurityReference.builder() + .reference(swaggerProperties().getAuthorization().getName()) + .scopes(authorizationScopes).build()); + } + @Override public void setBeanFactory(BeanFactory beanFactory) throws BeansException { @@ -206,7 +254,7 @@ public void setBeanFactory(BeanFactory beanFactory) throws BeansException { private List buildGlobalOperationParametersFromSwaggerProperties( List globalOperationParameters) { - List parameters = Lists.newArrayList(); + List parameters = newArrayList(); if (Objects.isNull(globalOperationParameters)) { return parameters; @@ -242,7 +290,7 @@ private List assemblyGlobalOperationParameters( .map(SwaggerProperties.GlobalOperationParameter::getName) .collect(Collectors.toSet()); - List resultOperationParameters = Lists.newArrayList(); + List resultOperationParameters = newArrayList(); if (Objects.nonNull(globalOperationParameters)) { for (SwaggerProperties.GlobalOperationParameter parameter : globalOperationParameters) { @@ -259,42 +307,43 @@ private List assemblyGlobalOperationParameters( /** * 设置全局响应消息 * - * @param swaggerProperties 支持 POST,GET,PUT,PATCH,DELETE,HEAD,OPTIONS,TRACE - * @param docketForBuilder + * @param swaggerProperties swaggerProperties 支持 POST,GET,PUT,PATCH,DELETE,HEAD,OPTIONS,TRACE + * @param docketForBuilder swagger docket builder */ private void buildGlobalResponseMessage(SwaggerProperties swaggerProperties, Docket docketForBuilder) { SwaggerProperties.GlobalResponseMessage globalResponseMessages = swaggerProperties.getGlobalResponseMessage(); - // POST,GET,PUT,PATCH,DELETE,HEAD,OPTIONS,TRACE 响应消息体 - List postResponseMessages = getResponseMessageList(globalResponseMessages.getPost()); - List getResponseMessages = getResponseMessageList(globalResponseMessages.getGet()); - List putResponseMessages = getResponseMessageList(globalResponseMessages.getPut()); - List patchResponseMessages = getResponseMessageList(globalResponseMessages.getPatch()); - List deleteResponseMessages = getResponseMessageList(globalResponseMessages.getDelete()); - List headResponseMessages = getResponseMessageList(globalResponseMessages.getHead()); - List optionsResponseMessages = getResponseMessageList(globalResponseMessages.getOptions()); - List trackResponseMessages = getResponseMessageList(globalResponseMessages.getTrace()); + /* POST,GET,PUT,PATCH,DELETE,HEAD,OPTIONS,TRACE 响应消息体 **/ + List postResponseMessages = getResponseMessageList(globalResponseMessages.getPost()); + List getResponseMessages = getResponseMessageList(globalResponseMessages.getGet()); + List putResponseMessages = getResponseMessageList(globalResponseMessages.getPut()); + List patchResponseMessages = getResponseMessageList(globalResponseMessages.getPatch()); + List deleteResponseMessages = getResponseMessageList(globalResponseMessages.getDelete()); + List headResponseMessages = getResponseMessageList(globalResponseMessages.getHead()); + List optionsResponseMessages = getResponseMessageList(globalResponseMessages.getOptions()); + List trackResponseMessages = getResponseMessageList(globalResponseMessages.getTrace()); docketForBuilder.useDefaultResponseMessages(swaggerProperties.getApplyDefaultResponseMessages()) - .globalResponseMessage(RequestMethod.POST, postResponseMessages) - .globalResponseMessage(RequestMethod.GET, getResponseMessages) - .globalResponseMessage(RequestMethod.PUT, putResponseMessages) - .globalResponseMessage(RequestMethod.PATCH, patchResponseMessages) - .globalResponseMessage(RequestMethod.DELETE, deleteResponseMessages) - .globalResponseMessage(RequestMethod.HEAD, headResponseMessages) - .globalResponseMessage(RequestMethod.OPTIONS, optionsResponseMessages) - .globalResponseMessage(RequestMethod.TRACE, trackResponseMessages); + .globalResponseMessage(RequestMethod.POST, postResponseMessages) + .globalResponseMessage(RequestMethod.GET, getResponseMessages) + .globalResponseMessage(RequestMethod.PUT, putResponseMessages) + .globalResponseMessage(RequestMethod.PATCH, patchResponseMessages) + .globalResponseMessage(RequestMethod.DELETE, deleteResponseMessages) + .globalResponseMessage(RequestMethod.HEAD, headResponseMessages) + .globalResponseMessage(RequestMethod.OPTIONS, optionsResponseMessages) + .globalResponseMessage(RequestMethod.TRACE, trackResponseMessages); } /** * 获取返回消息体列表 * - * @param globalResponseMessageBodyList + * @param globalResponseMessageBodyList 全局Code消息返回集合 * @return */ - private List getResponseMessageList(List globalResponseMessageBodyList) { + private List getResponseMessageList + (List globalResponseMessageBodyList) { List responseMessages = new ArrayList<>(); for (SwaggerProperties.GlobalResponseMessageBody globalResponseMessageBody : globalResponseMessageBodyList) { ResponseMessageBuilder responseMessageBuilder = new ResponseMessageBuilder(); diff --git a/src/main/java/com/spring4all/swagger/SwaggerProperties.java b/src/main/java/com/spring4all/swagger/SwaggerProperties.java index 8c2616c..0a43142 100644 --- a/src/main/java/com/spring4all/swagger/SwaggerProperties.java +++ b/src/main/java/com/spring4all/swagger/SwaggerProperties.java @@ -3,6 +3,10 @@ import lombok.Data; import lombok.NoArgsConstructor; import org.springframework.boot.context.properties.ConfigurationProperties; +import springfox.documentation.swagger.web.DocExpansion; +import springfox.documentation.swagger.web.ModelRendering; +import springfox.documentation.swagger.web.OperationsSorter; +import springfox.documentation.swagger.web.TagsSorter; import java.util.ArrayList; import java.util.LinkedHashMap; @@ -18,70 +22,118 @@ @ConfigurationProperties("swagger") public class SwaggerProperties { - /**是否开启swagger**/ + /** + * 是否开启swagger + **/ private Boolean enabled; - /**标题**/ + /** + * 标题 + **/ private String title = ""; - /**描述**/ + /** + * 描述 + **/ private String description = ""; - /**版本**/ + /** + * 版本 + **/ private String version = ""; - /**许可证**/ + /** + * 许可证 + **/ private String license = ""; - /**许可证URL**/ + /** + * 许可证URL + **/ private String licenseUrl = ""; - /**服务条款URL**/ + /** + * 服务条款URL + **/ private String termsOfServiceUrl = ""; - /**忽略的参数类型**/ - private List ignoredParameterTypes = new ArrayList<>(); + /** + * 忽略的参数类型 + **/ + private List> ignoredParameterTypes = new ArrayList<>(); private Contact contact = new Contact(); - /**swagger会解析的包路径**/ + /** + * swagger会解析的包路径 + **/ private String basePackage = ""; - /**swagger会解析的url规则**/ + /** + * swagger会解析的url规则 + **/ private List basePath = new ArrayList<>(); - /**在basePath基础上需要排除的url规则**/ + /** + * 在basePath基础上需要排除的url规则 + **/ private List excludePath = new ArrayList<>(); - /**分组文档**/ + /** + * 分组文档 + **/ private Map docket = new LinkedHashMap<>(); - /**host信息**/ + /** + * host信息 + **/ private String host = ""; - /**全局参数配置**/ + /** + * 全局参数配置 + **/ private List globalOperationParameters; - /** 页面功能配置 **/ + /** + * 页面功能配置 + **/ private UiConfig uiConfig = new UiConfig(); - /** 是否使用默认预定义的响应消息 ，默认 true **/ + /** + * 是否使用默认预定义的响应消息 ，默认 true + **/ private Boolean applyDefaultResponseMessages = true; - /** 全局响应消息 **/ + /** + * 全局响应消息 + **/ private GlobalResponseMessage globalResponseMessage; + /** + * 全局统一鉴权配置 + **/ + private Authorization authorization = new Authorization(); @Data @NoArgsConstructor - public static class GlobalOperationParameter{ - /**参数名**/ + public static class GlobalOperationParameter { + /** + * 参数名 + **/ private String name; - /**描述信息**/ + /** + * 描述信息 + **/ private String description; - /**指定参数类型**/ + /** + * 指定参数类型 + **/ private String modelRef; - /**参数放在哪个地方:header,query,path,body.form**/ + /** + * 参数放在哪个地方:header,query,path,body.form + **/ private String parameterType; - /**参数是否必须传**/ + /** + * 参数是否必须传 + **/ private String required; } @@ -90,33 +142,53 @@ public static class GlobalOperationParameter{ @NoArgsConstructor public static class DocketInfo { - /**标题**/ + /** + * 标题 + **/ private String title = ""; - /**描述**/ + /** + * 描述 + **/ private String description = ""; - /**版本**/ + /** + * 版本 + **/ private String version = ""; - /**许可证**/ + /** + * 许可证 + **/ private String license = ""; - /**许可证URL**/ + /** + * 许可证URL + **/ private String licenseUrl = ""; - /**服务条款URL**/ + /** + * 服务条款URL + **/ private String termsOfServiceUrl = ""; private Contact contact = new Contact(); - /**swagger会解析的包路径**/ + /** + * swagger会解析的包路径 + **/ private String basePackage = ""; - /**swagger会解析的url规则**/ + /** + * swagger会解析的url规则 + **/ private List basePath = new ArrayList<>(); - /**在basePath基础上需要排除的url规则**/ + /** + * 在basePath基础上需要排除的url规则 + **/ private List excludePath = new ArrayList<>(); private List globalOperationParameters; - /**忽略的参数类型**/ - private List ignoredParameterTypes = new ArrayList<>(); + /** + * 忽略的参数类型 + **/ + private List> ignoredParameterTypes = new ArrayList<>(); } @@ -124,11 +196,17 @@ public static class DocketInfo { @NoArgsConstructor public static class Contact { - /**联系人**/ + /** + * 联系人 + **/ private String name = ""; - /**联系人url**/ + /** + * 联系人url + **/ private String url = ""; - /**联系人email**/ + /** + * 联系人email + **/ private String email = ""; } @@ -137,28 +215,44 @@ public static class Contact { @NoArgsConstructor public static class GlobalResponseMessage { - /** POST 响应消息体 **/ + /** + * POST 响应消息体 + **/ List post = new ArrayList<>(); - /** GET 响应消息体 **/ + /** + * GET 响应消息体 + **/ List get = new ArrayList<>(); - /** PUT 响应消息体 **/ + /** + * PUT 响应消息体 + **/ List put = new ArrayList<>(); - /** PATCH 响应消息体 **/ + /** + * PATCH 响应消息体 + **/ List patch = new ArrayList<>(); - /** DELETE 响应消息体 **/ + /** + * DELETE 响应消息体 + **/ List delete = new ArrayList<>(); - /** HEAD 响应消息体 **/ + /** + * HEAD 响应消息体 + **/ List head = new ArrayList<>(); - /** OPTIONS 响应消息体 **/ + /** + * OPTIONS 响应消息体 + **/ List options = new ArrayList<>(); - /** TRACE 响应消息体 **/ + /** + * TRACE 响应消息体 + **/ List trace = new ArrayList<>(); } @@ -167,13 +261,19 @@ public static class GlobalResponseMessage { @NoArgsConstructor public static class GlobalResponseMessageBody { - /** 响应码 **/ + /** + * 响应码 + **/ private int code; - /** 响应消息 **/ + /** + * 响应消息 + **/ private String message; - /** 响应体 **/ + /** + * 响应体 + **/ private String modelRef; } @@ -183,20 +283,76 @@ public static class GlobalResponseMessageBody { @NoArgsConstructor public static class UiConfig { - private String validatorUrl; - private String docExpansion = "none"; // none | list - private String apiSorter = "alpha"; // alpha - private String defaultModelRendering = "schema"; // schema - /** 是否启用json编辑器 **/ + private String apiSorter = "alpha"; + + /** + * 是否启用json编辑器 + **/ private Boolean jsonEditor = false; - /** 是否显示请求头信息 **/ + /** + * 是否显示请求头信息 + **/ private Boolean showRequestHeaders = true; - /** 支持页面提交的请求类型 **/ + /** + * 支持页面提交的请求类型 + **/ private String submitMethods = "get,post,put,delete,patch"; - /** 请求超时时间 **/ + /** + * 请求超时时间 + **/ private Long requestTimeout = 10000L; + private Boolean deepLinking; + private Boolean displayOperationId; + private Integer defaultModelsExpandDepth; + private Integer defaultModelExpandDepth; + private ModelRendering defaultModelRendering; + + /** + * 是否显示请求耗时，默认false + */ + private Boolean displayRequestDuration = true; + /** + * 可选 none | list + */ + private DocExpansion docExpansion; + /** + * Boolean=false OR String + */ + private Object filter; + private Integer maxDisplayedTags; + private OperationsSorter operationsSorter; + private Boolean showExtensions; + private TagsSorter tagsSorter; + + /** + * Network + */ + private String validatorUrl; + } + + /** + * securitySchemes 支持方式之一 ApiKey + */ + @Data + @NoArgsConstructor + static class Authorization { + + /** + * 鉴权策略ID，对应 SecurityReferences ID + */ + private String name = "Authorization"; + + /** + * 鉴权传递的Header参数 + */ + private String keyName = "TOKEN"; + + /** + * 需要开启鉴权URL的正则 + */ + private String authRegex = "^.*$"; } }