From d747c1dd9e6e400535516e0330f3b5b48a9708d1 Mon Sep 17 00:00:00 2001 From: xiaohuo Date: Thu, 31 Aug 2017 16:54:05 +0800 Subject: [PATCH 1/9] =?UTF-8?q?1.4.0=20=E5=A2=9E=E5=8A=A0=E5=85=A8?= =?UTF-8?q?=E5=B1=80=E5=8F=82=E6=95=B0=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 3 ++ README.md | 12 ++++++ .../swagger/SwaggerAutoConfiguration.java | 42 ++++++++++++++----- .../didispace/swagger/SwaggerProperties.java | 13 ++++++ 4 files changed, 59 insertions(+), 11 deletions(-) diff --git a/.gitignore b/.gitignore index 6143e53..9ff7aa7 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,6 @@ # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml hs_err_pid* +.idea/ +spring-boot-starter-swagger.iml +target/ diff --git a/README.md b/README.md index ac3eded..5d74bbb 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,10 @@ swagger.contact.email=dyc87112@qq.com swagger.base-package=com.didispace swagger.base-path=/** swagger.exclude-path=/error, /ops/** +swagger.name=name +swagger.modelRef=string +swagger.parameterType=header +swagger.required=true ``` ## 配置说明 @@ -85,6 +89,10 @@ swagger.exclude-path=/error, /ops/** - swagger.base-path=需要处理的基础URL规则，默认：/** - swagger.exclude-path=需要排除的URL规则，默认：空 - swagger.host=文档的host信息，默认：空 +- swagger.name=参数名 +- swagger.modelRef=指定参数类型 +- swagger.parameterType=指定参数存放位置,可选header,query,path,body.form +- swagger.required=true=指定参数是否必传，true,false ``` > host属性从1.3.0.RELEASE开始支持 @@ -129,6 +137,10 @@ swagger.exclude-path=/ops/**, /error - swagger.docket..base-package=swagger扫描的基础包，默认：全扫描 - swagger.docket..base-path=需要处理的基础URL规则，默认：/** - swagger.docket..exclude-path=需要排除的URL规则，默认：空 +- swagger.docket..name=参数名 +- swagger.docket..modelRef=指定参数类型 +- swagger.docket..parameterType=指定参数存放位置,可选header,query,path,body.form +- swagger.docket..required=true=指定参数是否必传，true,false ``` 说明：``为swagger文档的分组名称，同一个项目中可以配置多个分组，用来划分不同的API文档。 diff --git a/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java b/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java index d1689be..70aa8ee 100644 --- a/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java +++ b/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java @@ -10,10 +10,13 @@ import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; +import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; +import springfox.documentation.schema.ModelRef; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; +import springfox.documentation.service.Parameter; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @@ -21,6 +24,8 @@ import java.util.LinkedList; import java.util.List; +import static com.google.common.collect.Lists.newArrayList; + /** * @author 翟永超 * Create date ：2017/8/7. @@ -43,7 +48,7 @@ public List createRestApi(SwaggerProperties swaggerProperties) { ConfigurableBeanFactory configurableBeanFactory = (ConfigurableBeanFactory) beanFactory; // 没有分组 - if(swaggerProperties.getDocket().size() == 0) { + if (swaggerProperties.getDocket().size() == 0) { ApiInfo apiInfo = new ApiInfoBuilder() .title(swaggerProperties.getTitle()) .description(swaggerProperties.getDescription()) @@ -58,23 +63,31 @@ public List createRestApi(SwaggerProperties swaggerProperties) { // base-path处理 // 当没有配置任何path的时候，解析/** - if(swaggerProperties.getBasePath().isEmpty()) { + if (swaggerProperties.getBasePath().isEmpty()) { swaggerProperties.getBasePath().add("/**"); } List> basePath = new ArrayList(); - for(String path : swaggerProperties.getBasePath()) { + for (String path : swaggerProperties.getBasePath()) { basePath.add(PathSelectors.ant(path)); } // exclude-path处理 List> excludePath = new ArrayList(); - for(String path : swaggerProperties.getExcludePath()) { + for (String path : swaggerProperties.getExcludePath()) { excludePath.add(PathSelectors.ant(path)); } + Docket docket = new Docket(DocumentationType.SWAGGER_2) .host(swaggerProperties.getHost()) .apiInfo(apiInfo) + .globalOperationParameters(newArrayList(new ParameterBuilder() + .name(swaggerProperties.getName()) + .description(swaggerProperties.getDescription()) + .modelRef(new ModelRef(swaggerProperties.getModelRef())) + .parameterType(swaggerProperties.getParameterType()) + .required(Boolean.parseBoolean(swaggerProperties.getRequired())) + .build())) .select() .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage())) .paths( @@ -91,7 +104,7 @@ public List createRestApi(SwaggerProperties swaggerProperties) { // 分组创建 List docketList = new LinkedList<>(); - for(String groupName : swaggerProperties.getDocket().keySet()) { + for (String groupName : swaggerProperties.getDocket().keySet()) { SwaggerProperties.DocketInfo docketInfo = swaggerProperties.getDocket().get(groupName); ApiInfo apiInfo = new ApiInfoBuilder() @@ -102,9 +115,9 @@ public List createRestApi(SwaggerProperties swaggerProperties) { .licenseUrl(docketInfo.getLicenseUrl().isEmpty() ? swaggerProperties.getLicenseUrl() : docketInfo.getLicenseUrl()) .contact( new Contact( - docketInfo.getContact().getName().isEmpty() ? swaggerProperties.getContact().getName() : docketInfo.getContact().getName(), - docketInfo.getContact().getUrl().isEmpty() ? swaggerProperties.getContact().getUrl() : docketInfo.getContact().getUrl(), - docketInfo.getContact().getEmail().isEmpty() ? swaggerProperties.getContact().getEmail() : docketInfo.getContact().getEmail() + docketInfo.getContact().getName().isEmpty() ? swaggerProperties.getContact().getName() : docketInfo.getContact().getName(), + docketInfo.getContact().getUrl().isEmpty() ? swaggerProperties.getContact().getUrl() : docketInfo.getContact().getUrl(), + docketInfo.getContact().getEmail().isEmpty() ? swaggerProperties.getContact().getEmail() : docketInfo.getContact().getEmail() ) ) .termsOfServiceUrl(docketInfo.getTermsOfServiceUrl().isEmpty() ? swaggerProperties.getTermsOfServiceUrl() : docketInfo.getTermsOfServiceUrl()) @@ -112,23 +125,30 @@ public List createRestApi(SwaggerProperties swaggerProperties) { // base-path处理 // 当没有配置任何path的时候，解析/** - if(docketInfo.getBasePath().isEmpty()) { + if (docketInfo.getBasePath().isEmpty()) { docketInfo.getBasePath().add("/**"); } List> basePath = new ArrayList(); - for(String path : docketInfo.getBasePath()) { + for (String path : docketInfo.getBasePath()) { basePath.add(PathSelectors.ant(path)); } // exclude-path处理 List> excludePath = new ArrayList(); - for(String path : docketInfo.getExcludePath()) { + for (String path : docketInfo.getExcludePath()) { excludePath.add(PathSelectors.ant(path)); } Docket docket = new Docket(DocumentationType.SWAGGER_2) .host(swaggerProperties.getHost()) .apiInfo(apiInfo) + .globalOperationParameters(newArrayList(new ParameterBuilder() + .name(swaggerProperties.getName()) + .description(swaggerProperties.getDescription()) + .modelRef(new ModelRef(swaggerProperties.getModelRef())) + .parameterType(swaggerProperties.getParameterType()) + .required(Boolean.parseBoolean(swaggerProperties.getRequired())) + .build())) .groupName(groupName) .select() .apis(RequestHandlerSelectors.basePackage(docketInfo.getBasePackage())) diff --git a/src/main/java/com/didispace/swagger/SwaggerProperties.java b/src/main/java/com/didispace/swagger/SwaggerProperties.java index cafc22d..492522a 100644 --- a/src/main/java/com/didispace/swagger/SwaggerProperties.java +++ b/src/main/java/com/didispace/swagger/SwaggerProperties.java @@ -3,6 +3,7 @@ import lombok.Data; import lombok.NoArgsConstructor; import org.springframework.boot.context.properties.ConfigurationProperties; +import springfox.documentation.schema.ModelRef; import java.util.ArrayList; import java.util.LinkedHashMap; @@ -31,6 +32,18 @@ public class SwaggerProperties { /**服务条款URL**/ private String termsOfServiceUrl = ""; + /**参数名**/ + private String name; + + /**指定参数类型**/ + private String modelRef; + + /**参数放在哪个地方:header,query,path,body.form**/ + private String parameterType; + + /**参数是否必须传**/ + private String required; + private Contact contact = new Contact(); /**swagger会解析的包路径**/ From 8b450a528af906ed1a28b0e149214e366f963595 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=A8=8B=E5=BA=8F=E7=8C=BFDD-=E7=BF=9F=E6=B0=B8=E8=B6=85?= Date: Fri, 1 Sep 2017 10:01:54 +0800 Subject: [PATCH 2/9] Create .travis.yml --- .travis.yml | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .travis.yml diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..a322442 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,6 @@ +language: java + +jdk: + - oraclejdk8 + +install: mvn install -DskipTests=true -Dmaven.javadoc.skip=true From d75587a21936f8fed038f1de1c9df889dcbc39d0 Mon Sep 17 00:00:00 2001 From: xiaohuo Date: Fri, 1 Sep 2017 23:55:17 +0800 Subject: [PATCH 3/9] =?UTF-8?q?1.4.0=20=E6=9B=B4=E6=96=B0=E5=85=A8?= =?UTF-8?q?=E5=B1=80=E5=8F=82=E6=95=B0=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../swagger/SwaggerAutoConfiguration.java | 37 ++++++++++++------- .../didispace/swagger/SwaggerProperties.java | 36 ++++++++++++------ 2 files changed, 47 insertions(+), 26 deletions(-) diff --git a/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java b/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java index 70aa8ee..baa8fb6 100644 --- a/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java +++ b/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java @@ -2,6 +2,7 @@ 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; @@ -81,13 +82,7 @@ public List createRestApi(SwaggerProperties swaggerProperties) { Docket docket = new Docket(DocumentationType.SWAGGER_2) .host(swaggerProperties.getHost()) .apiInfo(apiInfo) - .globalOperationParameters(newArrayList(new ParameterBuilder() - .name(swaggerProperties.getName()) - .description(swaggerProperties.getDescription()) - .modelRef(new ModelRef(swaggerProperties.getModelRef())) - .parameterType(swaggerProperties.getParameterType()) - .required(Boolean.parseBoolean(swaggerProperties.getRequired())) - .build())) + .globalOperationParameters(buildGlobalOperationParametersFromSwaggerProperties(swaggerProperties)) .select() .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage())) .paths( @@ -142,13 +137,13 @@ public List createRestApi(SwaggerProperties swaggerProperties) { Docket docket = new Docket(DocumentationType.SWAGGER_2) .host(swaggerProperties.getHost()) .apiInfo(apiInfo) - .globalOperationParameters(newArrayList(new ParameterBuilder() - .name(swaggerProperties.getName()) - .description(swaggerProperties.getDescription()) - .modelRef(new ModelRef(swaggerProperties.getModelRef())) - .parameterType(swaggerProperties.getParameterType()) - .required(Boolean.parseBoolean(swaggerProperties.getRequired())) - .build())) +// .globalOperationParameters(newArrayList(new ParameterBuilder() +// .name(swaggerProperties.getName()) +// .description(swaggerProperties.getDescription()) +// .modelRef(new ModelRef(swaggerProperties.getModelRef())) +// .parameterType(swaggerProperties.getParameterType()) +// .required(Boolean.parseBoolean(swaggerProperties.getRequired())) +// .build())) .groupName(groupName) .select() .apis(RequestHandlerSelectors.basePackage(docketInfo.getBasePackage())) @@ -170,4 +165,18 @@ public List createRestApi(SwaggerProperties swaggerProperties) { public void setBeanFactory(BeanFactory beanFactory) throws BeansException { this.beanFactory = beanFactory; } + + private List buildGlobalOperationParametersFromSwaggerProperties(SwaggerProperties swaggerProperties) { + List parameters = Lists.newArrayList(); + for (int i = 0; i < swaggerProperties.getGlobalOperationParameters().size(); i++) { + parameters.add(new ParameterBuilder() + .name(swaggerProperties.getGlobalOperationParameters().get(i).getName()) + .description(swaggerProperties.getGlobalOperationParameters().get(i).getDescription()) + .modelRef(new ModelRef(swaggerProperties.getGlobalOperationParameters().get(i).getModelRef())) + .parameterType(swaggerProperties.getGlobalOperationParameters().get(i).getParameterType()) + .required(Boolean.parseBoolean(swaggerProperties.getGlobalOperationParameters().get(i).getRequired())) + .build()); + } + return parameters; + } } diff --git a/src/main/java/com/didispace/swagger/SwaggerProperties.java b/src/main/java/com/didispace/swagger/SwaggerProperties.java index 492522a..046afd6 100644 --- a/src/main/java/com/didispace/swagger/SwaggerProperties.java +++ b/src/main/java/com/didispace/swagger/SwaggerProperties.java @@ -32,18 +32,6 @@ public class SwaggerProperties { /**服务条款URL**/ private String termsOfServiceUrl = ""; - /**参数名**/ - private String name; - - /**指定参数类型**/ - private String modelRef; - - /**参数放在哪个地方:header,query,path,body.form**/ - private String parameterType; - - /**参数是否必须传**/ - private String required; - private Contact contact = new Contact(); /**swagger会解析的包路径**/ @@ -60,6 +48,30 @@ public class SwaggerProperties { /**host信息**/ private String host = ""; + /**全局参数配置**/ + private List globalOperationParameters; + + + @Data + @NoArgsConstructor + @ConfigurationProperties("swagger.globalOperationParameters") + public static class GlobalOperationParameter{ + /**参数名**/ + private String name; + + /**描述信息**/ + private String description; + + /**指定参数类型**/ + private String modelRef; + + /**参数放在哪个地方:header,query,path,body.form**/ + private String parameterType; + + /**参数是否必须传**/ + private String required; + } + @Data @NoArgsConstructor public static class DocketInfo { From 501229f02e5c16ced042a1b5218e6ca5f3c46be6 Mon Sep 17 00:00:00 2001 From: xiaohuo Date: Fri, 1 Sep 2017 23:57:05 +0800 Subject: [PATCH 4/9] =?UTF-8?q?1.4.0=20=E4=BF=AE=E6=94=B9=E5=88=86?= =?UTF-8?q?=E7=BB=84=E5=85=A8=E5=B1=80=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../didispace/swagger/SwaggerAutoConfiguration.java | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java b/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java index baa8fb6..6f91a2f 100644 --- a/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java +++ b/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java @@ -25,8 +25,6 @@ import java.util.LinkedList; import java.util.List; -import static com.google.common.collect.Lists.newArrayList; - /** * @author 翟永超 * Create date ：2017/8/7. @@ -137,13 +135,7 @@ public List createRestApi(SwaggerProperties swaggerProperties) { Docket docket = new Docket(DocumentationType.SWAGGER_2) .host(swaggerProperties.getHost()) .apiInfo(apiInfo) -// .globalOperationParameters(newArrayList(new ParameterBuilder() -// .name(swaggerProperties.getName()) -// .description(swaggerProperties.getDescription()) -// .modelRef(new ModelRef(swaggerProperties.getModelRef())) -// .parameterType(swaggerProperties.getParameterType()) -// .required(Boolean.parseBoolean(swaggerProperties.getRequired())) -// .build())) + .globalOperationParameters(buildGlobalOperationParametersFromSwaggerProperties(swaggerProperties)) .groupName(groupName) .select() .apis(RequestHandlerSelectors.basePackage(docketInfo.getBasePackage())) From 0d271957cae713e3b95719423dcd4e74a8858052 Mon Sep 17 00:00:00 2001 From: xiaohuo Date: Sat, 2 Sep 2017 01:07:41 +0800 Subject: [PATCH 5/9] =?UTF-8?q?1.4.0=20=E4=BF=AE=E6=94=B9readme=E6=96=87?= =?UTF-8?q?=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 5d74bbb..f7205ee 100644 --- a/README.md +++ b/README.md @@ -65,10 +65,16 @@ swagger.contact.email=dyc87112@qq.com swagger.base-package=com.didispace swagger.base-path=/** swagger.exclude-path=/error, /ops/** -swagger.name=name -swagger.modelRef=string -swagger.parameterType=header -swagger.required=true +swagger.globalOperationParameters[0].name=name one +swagger.globalOperationParameters[0].description=some description one +swagger.globalOperationParameters[0].modelRef=string +swagger.globalOperationParameters[0].parameterType=header +swagger.globalOperationParameters[0].required=true +swagger.globalOperationParameters[1].name=name two +swagger.globalOperationParameters[1].description=some description two +swagger.globalOperationParameters[1].modelRef=string +swagger.globalOperationParameters[1].parameterType=body +swagger.globalOperationParameters[1].required=false ``` ## 配置说明 @@ -89,10 +95,11 @@ swagger.required=true - swagger.base-path=需要处理的基础URL规则，默认：/** - swagger.exclude-path=需要排除的URL规则，默认：空 - swagger.host=文档的host信息，默认：空 -- swagger.name=参数名 -- swagger.modelRef=指定参数类型 -- swagger.parameterType=指定参数存放位置,可选header,query,path,body.form -- swagger.required=true=指定参数是否必传，true,false +- swagger.globalOperationParameters[0].name=参数名 +- swagger.globalOperationParameters[0].description=描述信息 +- swagger.globalOperationParameters[0].modelRef=指定参数类型 +- swagger.globalOperationParameters[0].parameterType=指定参数存放位置,可选header,query,path,body.form +- swagger.globalOperationParameters[0].required=指定参数是否必传，true,false ``` > host属性从1.3.0.RELEASE开始支持 From 3dd02c0ff6360d7fde0df854604d6396a713ff09 Mon Sep 17 00:00:00 2001 From: xiaohuo Date: Mon, 4 Sep 2017 14:32:57 +0800 Subject: [PATCH 6/9] =?UTF-8?q?1.4.0=20=E5=AE=8C=E5=96=84=E5=88=86?= =?UTF-8?q?=E7=BB=84=E9=85=8D=E7=BD=AE=E5=92=8C=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 14 +++++ .../swagger/SwaggerAutoConfiguration.java | 53 +++++++++++++++---- .../didispace/swagger/SwaggerProperties.java | 4 +- 3 files changed, 61 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index f7205ee..75a812d 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,7 @@ swagger.globalOperationParameters[1].required=false - swagger.globalOperationParameters[0].required=指定参数是否必传，true,false ``` + > host属性从1.3.0.RELEASE开始支持 ### Path规则说明 @@ -148,10 +149,15 @@ swagger.exclude-path=/ops/**, /error - swagger.docket..modelRef=指定参数类型 - swagger.docket..parameterType=指定参数存放位置,可选header,query,path,body.form - swagger.docket..required=true=指定参数是否必传，true,false +- swagger.docket..globalOperationParameters[0].name=参数名 +- swagger.docket..globalOperationParameters[0].description=描述信息 +- swagger.docket..globalOperationParameters[0].modelRef=指定参数存放位置,可选header,query,path,body.form +- swagger.docket..globalOperationParameters[0].parameterType=指定参数是否必传，true,false ``` 说明：``为swagger文档的分组名称，同一个项目中可以配置多个分组，用来划分不同的API文档。 + **分组配置示例** ```properties @@ -163,13 +169,21 @@ swagger.docket.aaa.contact.name=zhaiyongchao swagger.docket.aaa.contact.url=http://spring4all.com/ swagger.docket.aaa.contact.email=didi@potatomato.club swagger.docket.aaa.excludePath=/ops/** +swagger.docket.aaa.globalOperationParameters[0].name=name three +swagger.docket.aaa.globalOperationParameters[0].description=some description three override +swagger.docket.aaa.globalOperationParameters[0].modelRef=string +swagger.docket.aaa.globalOperationParameters[0].parameterType=header swagger.docket.bbb.title=group-bbb swagger.docket.bbb.basePackage=com.yonghui + + ``` 说明：默认配置与分组配置可以一起使用。在分组配置中没有配置的内容将使用默认配置替代，所以默认配置可以作为分组配置公共部分属性的配置。 +`swagger.docket.aaa.globalOperationParameters[0].name` 会覆盖同名的全局配置 + ### JSR-303校验注解支持 支持对JSR-303校验注解的展示，如下图所示： diff --git a/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java b/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java index 6f91a2f..7403703 100644 --- a/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java +++ b/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java @@ -24,6 +24,8 @@ import java.util.ArrayList; import java.util.LinkedList; import java.util.List; +import java.util.Set; +import java.util.stream.Collectors; /** * @author 翟永超 @@ -80,7 +82,8 @@ public List createRestApi(SwaggerProperties swaggerProperties) { Docket docket = new Docket(DocumentationType.SWAGGER_2) .host(swaggerProperties.getHost()) .apiInfo(apiInfo) - .globalOperationParameters(buildGlobalOperationParametersFromSwaggerProperties(swaggerProperties)) + .globalOperationParameters(buildGlobalOperationParametersFromSwaggerProperties( + swaggerProperties.getGlobalOperationParameters())) .select() .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage())) .paths( @@ -135,7 +138,8 @@ public List createRestApi(SwaggerProperties swaggerProperties) { Docket docket = new Docket(DocumentationType.SWAGGER_2) .host(swaggerProperties.getHost()) .apiInfo(apiInfo) - .globalOperationParameters(buildGlobalOperationParametersFromSwaggerProperties(swaggerProperties)) + .globalOperationParameters(assemblyGlobalOperationParameters(swaggerProperties.getGlobalOperationParameters(), + docketInfo.getGlobalOperationParameters())) .groupName(groupName) .select() .apis(RequestHandlerSelectors.basePackage(docketInfo.getBasePackage())) @@ -158,17 +162,48 @@ public void setBeanFactory(BeanFactory beanFactory) throws BeansException { this.beanFactory = beanFactory; } - private List buildGlobalOperationParametersFromSwaggerProperties(SwaggerProperties swaggerProperties) { + private List buildGlobalOperationParametersFromSwaggerProperties( + List globalOperationParameters) { List parameters = Lists.newArrayList(); - for (int i = 0; i < swaggerProperties.getGlobalOperationParameters().size(); i++) { + for (SwaggerProperties.GlobalOperationParameter globalOperationParameter : globalOperationParameters) { parameters.add(new ParameterBuilder() - .name(swaggerProperties.getGlobalOperationParameters().get(i).getName()) - .description(swaggerProperties.getGlobalOperationParameters().get(i).getDescription()) - .modelRef(new ModelRef(swaggerProperties.getGlobalOperationParameters().get(i).getModelRef())) - .parameterType(swaggerProperties.getGlobalOperationParameters().get(i).getParameterType()) - .required(Boolean.parseBoolean(swaggerProperties.getGlobalOperationParameters().get(i).getRequired())) + .name(globalOperationParameter.getName()) + .description(globalOperationParameter.getDescription()) + .modelRef(new ModelRef(globalOperationParameter.getModelRef())) + .parameterType(globalOperationParameter.getParameterType()) + .required(Boolean.parseBoolean(globalOperationParameter.getRequired())) .build()); } return parameters; } + + /** + * 局部参数按照name覆盖局部参数 + * + * @param globalOperationParameters + * @param docketOperationParameters + * @return + */ + private List assemblyGlobalOperationParameters( + List globalOperationParameters, + List docketOperationParameters) { + + if (docketOperationParameters == null || docketOperationParameters.isEmpty()) { + return buildGlobalOperationParametersFromSwaggerProperties(globalOperationParameters); + } + + Set docketNames = docketOperationParameters.stream() + .map(SwaggerProperties.GlobalOperationParameter::getName) + .collect(Collectors.toSet()); + + List resultOperationParameters = Lists.newArrayList(); + + for (SwaggerProperties.GlobalOperationParameter parameter : globalOperationParameters) { + if (!docketNames.contains(parameter.getName())) { + resultOperationParameters.add(parameter); + } + } + resultOperationParameters.addAll(docketOperationParameters); + return buildGlobalOperationParametersFromSwaggerProperties(resultOperationParameters); + } } diff --git a/src/main/java/com/didispace/swagger/SwaggerProperties.java b/src/main/java/com/didispace/swagger/SwaggerProperties.java index 046afd6..4511360 100644 --- a/src/main/java/com/didispace/swagger/SwaggerProperties.java +++ b/src/main/java/com/didispace/swagger/SwaggerProperties.java @@ -54,7 +54,6 @@ public class SwaggerProperties { @Data @NoArgsConstructor - @ConfigurationProperties("swagger.globalOperationParameters") public static class GlobalOperationParameter{ /**参数名**/ private String name; @@ -70,6 +69,7 @@ public static class GlobalOperationParameter{ /**参数是否必须传**/ private String required; + } @Data @@ -99,6 +99,8 @@ public static class DocketInfo { /**在basePath基础上需要排除的url规则**/ private List excludePath = new ArrayList<>(); + private List globalOperationParameters; + } @Data From f21899367937e0e306194e6b94df635943182eeb Mon Sep 17 00:00:00 2001 From: didi Date: Thu, 7 Sep 2017 17:14:50 +0800 Subject: [PATCH 7/9] =?UTF-8?q?1.4.0=20=E5=8A=9F=E8=83=BD=E6=9B=B4?= =?UTF-8?q?=E6=96=B0=EF=BC=9A=E5=A2=9E=E5=8A=A0=E6=98=AF=E5=90=A6=E5=90=AF?= =?UTF-8?q?=E5=8A=A8swagger=E5=8A=9F=E8=83=BD=E7=9A=84=E9=85=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pom.xml | 2 +- .../didispace/swagger/EnableSwagger2Doc.java | 5 +---- .../swagger/Swagger2Configuration.java | 21 +++++++++++++++++++ .../swagger/SwaggerAutoConfiguration.java | 6 ++++++ .../didispace/swagger/SwaggerProperties.java | 3 +++ 5 files changed, 32 insertions(+), 5 deletions(-) create mode 100644 src/main/java/com/didispace/swagger/Swagger2Configuration.java diff --git a/pom.xml b/pom.xml index e021185..680f71e 100644 --- a/pom.xml +++ b/pom.xml @@ -6,7 +6,7 @@ com.didispace spring-boot-starter-swagger - 1.3.0.RELEASE + 1.4.0.RELEASE spring-boot-starter-swagger https://github.com/dyc87112/spring-boot-starter-swagger diff --git a/src/main/java/com/didispace/swagger/EnableSwagger2Doc.java b/src/main/java/com/didispace/swagger/EnableSwagger2Doc.java index 01b5741..0ea7844 100644 --- a/src/main/java/com/didispace/swagger/EnableSwagger2Doc.java +++ b/src/main/java/com/didispace/swagger/EnableSwagger2Doc.java @@ -1,8 +1,6 @@ package com.didispace.swagger; import org.springframework.context.annotation.Import; -import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration; -import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.lang.annotation.*; @@ -15,8 +13,7 @@ @Retention(RetentionPolicy.RUNTIME) @Documented @Inherited -@EnableSwagger2 -@Import({SwaggerAutoConfiguration.class, BeanValidatorPluginsConfiguration.class}) +@Import({SwaggerAutoConfiguration.class}) public @interface EnableSwagger2Doc { diff --git a/src/main/java/com/didispace/swagger/Swagger2Configuration.java b/src/main/java/com/didispace/swagger/Swagger2Configuration.java new file mode 100644 index 0000000..a46de38 --- /dev/null +++ b/src/main/java/com/didispace/swagger/Swagger2Configuration.java @@ -0,0 +1,21 @@ +package com.didispace.swagger; + +import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; +import org.springframework.context.annotation.Configuration; +import org.springframework.context.annotation.Import; +import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration; +import springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration; + +/** + * @author 翟永超 + * @create 2017/9/7. + * @blog http://blog.didispace.com + */ +@Configuration +@ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true) +@Import({ + Swagger2DocumentationConfiguration.class, + BeanValidatorPluginsConfiguration.class +}) +public class Swagger2Configuration { +} diff --git a/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java b/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java index 7403703..7ef9f32 100644 --- a/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java +++ b/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java @@ -8,8 +8,10 @@ import org.springframework.beans.factory.BeanFactoryAware; import org.springframework.beans.factory.config.ConfigurableBeanFactory; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; +import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; +import org.springframework.context.annotation.Import; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.builders.PathSelectors; @@ -33,6 +35,9 @@ * My blog： http://blog.didispace.com */ @Configuration +@Import({ + Swagger2Configuration.class +}) public class SwaggerAutoConfiguration implements BeanFactoryAware { private BeanFactory beanFactory; @@ -45,6 +50,7 @@ public SwaggerProperties swaggerProperties() { @Bean @ConditionalOnMissingBean + @ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true) public List createRestApi(SwaggerProperties swaggerProperties) { ConfigurableBeanFactory configurableBeanFactory = (ConfigurableBeanFactory) beanFactory; diff --git a/src/main/java/com/didispace/swagger/SwaggerProperties.java b/src/main/java/com/didispace/swagger/SwaggerProperties.java index 4511360..75314ff 100644 --- a/src/main/java/com/didispace/swagger/SwaggerProperties.java +++ b/src/main/java/com/didispace/swagger/SwaggerProperties.java @@ -19,6 +19,9 @@ @ConfigurationProperties("swagger") public class SwaggerProperties { + /**是否开启swagger**/ + private Boolean enabled; + /**标题**/ private String title = ""; /**描述**/ From 83a1d79ea0c95290235e70ec2c8e83c161343b15 Mon Sep 17 00:00:00 2001 From: didi Date: Thu, 7 Sep 2017 17:22:25 +0800 Subject: [PATCH 8/9] =?UTF-8?q?=E4=BF=AE=E6=94=B9=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 75a812d..9f96805 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ com.didispace spring-boot-starter-swagger - 1.3.0.RELEASE + 1.4.0.RELEASE ``` @@ -53,9 +53,11 @@ public class Bootstrap { ## 配置示例 ```properties +swagger.enabled=true + swagger.title=spring-boot-starter-swagger swagger.description=Starter for swagger 2.x -swagger.version=1.3.0.RELEASE +swagger.version=1.4.0.RELEASE swagger.license=Apache License, Version 2.0 swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger @@ -65,6 +67,7 @@ swagger.contact.email=dyc87112@qq.com swagger.base-package=com.didispace swagger.base-path=/** swagger.exclude-path=/error, /ops/** + swagger.globalOperationParameters[0].name=name one swagger.globalOperationParameters[0].description=some description one swagger.globalOperationParameters[0].modelRef=string @@ -82,6 +85,7 @@ swagger.globalOperationParameters[1].required=false ### 默认配置 ``` +- swagger.enabled=是否启用swagger，默认：true - swagger.title=标题 - swagger.description=描述 - swagger.version=版本 @@ -103,7 +107,11 @@ swagger.globalOperationParameters[1].required=false ``` -> host属性从1.3.0.RELEASE开始支持 +> `1.3.0.RELEASE`新增：`swagger.host`属性，同时也支持指定docket的配置 +> +> `1.4.0.RELEASE`新增： +> - `swagger.enabled`：用于开关swagger的配置 +> - `swagger.globalOperationParameters`：用于设置全局的参数，比如：header部分的accessToken等。该参数支持指定docket的配置。 ### Path规则说明 @@ -176,13 +184,9 @@ swagger.docket.aaa.globalOperationParameters[0].parameterType=header swagger.docket.bbb.title=group-bbb swagger.docket.bbb.basePackage=com.yonghui - - ``` -说明：默认配置与分组配置可以一起使用。在分组配置中没有配置的内容将使用默认配置替代，所以默认配置可以作为分组配置公共部分属性的配置。 - -`swagger.docket.aaa.globalOperationParameters[0].name` 会覆盖同名的全局配置 +说明：默认配置与分组配置可以一起使用。在分组配置中没有配置的内容将使用默认配置替代，所以默认配置可以作为分组配置公共部分属性的配置。`swagger.docket.aaa.globalOperationParameters[0].name`会覆盖同名的全局配置。 ### JSR-303校验注解支持 From ecd50c4345d72510795ada080e2a5da1135dc5bf Mon Sep 17 00:00:00 2001 From: didi Date: Thu, 7 Sep 2017 17:30:31 +0800 Subject: [PATCH 9/9] =?UTF-8?q?=E8=B0=83=E6=95=B4=E6=B3=A8=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../java/com/didispace/swagger/Swagger2Configuration.java | 4 ++-- .../java/com/didispace/swagger/SwaggerAutoConfiguration.java | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/main/java/com/didispace/swagger/Swagger2Configuration.java b/src/main/java/com/didispace/swagger/Swagger2Configuration.java index a46de38..0703d28 100644 --- a/src/main/java/com/didispace/swagger/Swagger2Configuration.java +++ b/src/main/java/com/didispace/swagger/Swagger2Configuration.java @@ -8,8 +8,8 @@ /** * @author 翟永超 - * @create 2017/9/7. - * @blog http://blog.didispace.com + * Create Date： 2017/9/7. + * My blog： http://blog.didispace.com */ @Configuration @ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true) diff --git a/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java b/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java index 7ef9f32..9529c64 100644 --- a/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java +++ b/src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java @@ -31,7 +31,7 @@ /** * @author 翟永超 - * Create date ：2017/8/7. + * Create date：2017/8/7. * My blog： http://blog.didispace.com */ @Configuration