Merge pull request #16 from dyc87112/1.4.0-xiaohou

程序猿DD-翟永超 · web-flow · commit f76eef338a70 · 2017-09-07T16:55:39.000+08:00
1.4.0 增加全局参数配置
diff --git 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/.travis.yml b/.travis.yml
@@ -0,0 +1,6 @@
+language: java
+
+jdk:
+  - oraclejdk8
+  
+install: mvn install -DskipTests=true -Dmaven.javadoc.skip=true
diff --git a/README.md b/README.md
@@ -65,6 +65,16 @@ 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
+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
 ```
 
 ## 配置说明
@@ -85,8 +95,14 @@ swagger.exclude-path=/error, /ops/**
 - swagger.base-path=需要处理的基础URL规则，默认：/**
 - swagger.exclude-path=需要排除的URL规则，默认：空
 - swagger.host=文档的host信息，默认：空
+- 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开始支持
 
 ### Path规则说明
@@ -129,10 +145,19 @@ swagger.exclude-path=/ops/**, /error
 - swagger.docket.<name>.base-package=swagger扫描的基础包，默认：全扫描
 - swagger.docket.<name>.base-path=需要处理的基础URL规则，默认：/**
 - swagger.docket.<name>.exclude-path=需要排除的URL规则，默认：空
+- swagger.docket.<name>.name=参数名
+- swagger.docket.<name>.modelRef=指定参数类型
+- swagger.docket.<name>.parameterType=指定参数存放位置,可选header,query,path,body.form
+- swagger.docket.<name>.required=true=指定参数是否必传，true,false
+- swagger.docket.<name>.globalOperationParameters[0].name=参数名
+- swagger.docket.<name>.globalOperationParameters[0].description=描述信息
+- swagger.docket.<name>.globalOperationParameters[0].modelRef=指定参数存放位置,可选header,query,path,body.form
+- swagger.docket.<name>.globalOperationParameters[0].parameterType=指定参数是否必传，true,false
 ```
 
 说明：`<name>`为swagger文档的分组名称，同一个项目中可以配置多个分组，用来划分不同的API文档。
 
+
 **分组配置示例**
 
 ```properties
@@ -144,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
@@ -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;
@@ -10,16 +11,21 @@
 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;
 
 import java.util.ArrayList;
 import java.util.LinkedList;
 import java.util.List;
+import java.util.Set;
+import java.util.stream.Collectors;
 
 /**
  * @author 翟永超
@@ -43,7 +49,7 @@ public List<Docket> 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 +64,26 @@ public List<Docket> createRestApi(SwaggerProperties swaggerProperties) {
 
             // base-path处理
             // 当没有配置任何path的时候，解析/**
-            if(swaggerProperties.getBasePath().isEmpty()) {
+            if (swaggerProperties.getBasePath().isEmpty()) {
                 swaggerProperties.getBasePath().add("/**");
             }
             List<Predicate<String>> basePath = new ArrayList();
-            for(String path : swaggerProperties.getBasePath()) {
+            for (String path : swaggerProperties.getBasePath()) {
                 basePath.add(PathSelectors.ant(path));
             }
 
             // exclude-path处理
             List<Predicate<String>> 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(buildGlobalOperationParametersFromSwaggerProperties(
+                            swaggerProperties.getGlobalOperationParameters()))
                     .select()
                     .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
                     .paths(
@@ -91,7 +100,7 @@ public List<Docket> createRestApi(SwaggerProperties swaggerProperties) {
 
         // 分组创建
         List<Docket> 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,33 +111,35 @@ public List<Docket> 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())
                     .build();
 
             // base-path处理
             // 当没有配置任何path的时候，解析/**
-            if(docketInfo.getBasePath().isEmpty()) {
+            if (docketInfo.getBasePath().isEmpty()) {
                 docketInfo.getBasePath().add("/**");
             }
             List<Predicate<String>> basePath = new ArrayList();
-            for(String path : docketInfo.getBasePath()) {
+            for (String path : docketInfo.getBasePath()) {
                 basePath.add(PathSelectors.ant(path));
             }
 
             // exclude-path处理
             List<Predicate<String>> 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(assemblyGlobalOperationParameters(swaggerProperties.getGlobalOperationParameters(),
+                            docketInfo.getGlobalOperationParameters()))
                     .groupName(groupName)
                     .select()
                     .apis(RequestHandlerSelectors.basePackage(docketInfo.getBasePackage()))
@@ -150,4 +161,49 @@ public List<Docket> createRestApi(SwaggerProperties swaggerProperties) {
     public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
         this.beanFactory = beanFactory;
     }
+
+    private List<Parameter> buildGlobalOperationParametersFromSwaggerProperties(
+            List<SwaggerProperties.GlobalOperationParameter> globalOperationParameters) {
+        List<Parameter> parameters = Lists.newArrayList();
+        for (SwaggerProperties.GlobalOperationParameter globalOperationParameter : globalOperationParameters) {
+            parameters.add(new ParameterBuilder()
+                    .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<Parameter> assemblyGlobalOperationParameters(
+            List<SwaggerProperties.GlobalOperationParameter> globalOperationParameters,
+            List<SwaggerProperties.GlobalOperationParameter> docketOperationParameters) {
+
+        if (docketOperationParameters == null || docketOperationParameters.isEmpty()) {
+            return buildGlobalOperationParametersFromSwaggerProperties(globalOperationParameters);
+        }
+
+        Set<String> docketNames = docketOperationParameters.stream()
+                .map(SwaggerProperties.GlobalOperationParameter::getName)
+                .collect(Collectors.toSet());
+
+        List<SwaggerProperties.GlobalOperationParameter> 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
@@ -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;
@@ -47,6 +48,30 @@ public class SwaggerProperties {
     /**host信息**/
     private String host = "";
 
+    /**全局参数配置**/
+    private List<GlobalOperationParameter> globalOperationParameters;
+
+
+    @Data
+    @NoArgsConstructor
+    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 {
@@ -74,6 +99,8 @@ public static class DocketInfo {
         /**在basePath基础上需要排除的url规则**/
         private List<String> excludePath = new ArrayList<>();
 
+        private List<GlobalOperationParameter> globalOperationParameters;
+
     }
 
     @Data
