Skip to content

Commit 02fb796

Browse files
author
程序猿DD-翟永超
authored
Merge pull request #17 from dyc87112/1.4.0
1.4.0
2 parents 3f72fce + ecd50c4 commit 02fb796

File tree

8 files changed

+177
-21
lines changed

8 files changed

+177
-21
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,6 @@
2020

2121
# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
2222
hs_err_pid*
23+
.idea/
24+
spring-boot-starter-swagger.iml
25+
target/

‎.travis.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
language: java
2+
3+
jdk:
4+
- oraclejdk8
5+
6+
install: mvn install -DskipTests=true -Dmaven.javadoc.skip=true

‎README.md

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
<dependency>
2727
<groupId>com.didispace</groupId>
2828
<artifactId>spring-boot-starter-swagger</artifactId>
29-
<version>1.3.0.RELEASE</version>
29+
<version>1.4.0.RELEASE</version>
3030
</dependency>
3131
```
3232

@@ -53,9 +53,11 @@ public class Bootstrap {
5353
## 配置示例
5454

5555
```properties
56+
swagger.enabled=true
57+
5658
swagger.title=spring-boot-starter-swagger
5759
swagger.description=Starter for swagger 2.x
58-
swagger.version=1.3.0.RELEASE
60+
swagger.version=1.4.0.RELEASE
5961
swagger.license=Apache License, Version 2.0
6062
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
6163
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
@@ -65,13 +67,25 @@ swagger.contact.email=dyc87112@qq.com
6567
swagger.base-package=com.didispace
6668
swagger.base-path=/**
6769
swagger.exclude-path=/error, /ops/**
70+
71+
swagger.globalOperationParameters[0].name=name one
72+
swagger.globalOperationParameters[0].description=some description one
73+
swagger.globalOperationParameters[0].modelRef=string
74+
swagger.globalOperationParameters[0].parameterType=header
75+
swagger.globalOperationParameters[0].required=true
76+
swagger.globalOperationParameters[1].name=name two
77+
swagger.globalOperationParameters[1].description=some description two
78+
swagger.globalOperationParameters[1].modelRef=string
79+
swagger.globalOperationParameters[1].parameterType=body
80+
swagger.globalOperationParameters[1].required=false
6881
```
6982

7083
## 配置说明
7184

7285
### 默认配置
7386

7487
```
88+
- swagger.enabled=是否启用swagger，默认：true
7589
- swagger.title=标题
7690
- swagger.description=描述
7791
- swagger.version=版本
@@ -85,9 +99,19 @@ swagger.exclude-path=/error, /ops/**
8599
- swagger.base-path=需要处理的基础URL规则，默认：/**
86100
- swagger.exclude-path=需要排除的URL规则，默认：空
87101
- swagger.host=文档的host信息，默认：空
102+
- swagger.globalOperationParameters[0].name=参数名
103+
- swagger.globalOperationParameters[0].description=描述信息
104+
- swagger.globalOperationParameters[0].modelRef=指定参数类型
105+
- swagger.globalOperationParameters[0].parameterType=指定参数存放位置,可选header,query,path,body.form
106+
- swagger.globalOperationParameters[0].required=指定参数是否必传，true,false
88107
```
89108

90-
> host属性从1.3.0.RELEASE开始支持
109+
110+
> `1.3.0.RELEASE`新增：`swagger.host`属性，同时也支持指定docket的配置
111+
>
112+
> `1.4.0.RELEASE`新增：
113+
> - `swagger.enabled`：用于开关swagger的配置
114+
> - `swagger.globalOperationParameters`：用于设置全局的参数，比如：header部分的accessToken等。该参数支持指定docket的配置。
91115
92116
### Path规则说明
93117

@@ -129,10 +153,19 @@ swagger.exclude-path=/ops/**, /error
129153
- swagger.docket.<name>.base-package=swagger扫描的基础包，默认：全扫描
130154
- swagger.docket.<name>.base-path=需要处理的基础URL规则，默认：/**
131155
- swagger.docket.<name>.exclude-path=需要排除的URL规则，默认：空
156+
- swagger.docket.<name>.name=参数名
157+
- swagger.docket.<name>.modelRef=指定参数类型
158+
- swagger.docket.<name>.parameterType=指定参数存放位置,可选header,query,path,body.form
159+
- swagger.docket.<name>.required=true=指定参数是否必传，true,false
160+
- swagger.docket.<name>.globalOperationParameters[0].name=参数名
161+
- swagger.docket.<name>.globalOperationParameters[0].description=描述信息
162+
- swagger.docket.<name>.globalOperationParameters[0].modelRef=指定参数存放位置,可选header,query,path,body.form
163+
- swagger.docket.<name>.globalOperationParameters[0].parameterType=指定参数是否必传，true,false
132164
```
133165

134166
说明：`<name>`为swagger文档的分组名称，同一个项目中可以配置多个分组，用来划分不同的API文档。
135167

168+
136169
**分组配置示例**
137170

138171
```properties
@@ -144,12 +177,16 @@ swagger.docket.aaa.contact.name=zhaiyongchao
144177
swagger.docket.aaa.contact.url=http://spring4all.com/
145178
swagger.docket.aaa.contact.email=didi@potatomato.club
146179
swagger.docket.aaa.excludePath=/ops/**
180+
swagger.docket.aaa.globalOperationParameters[0].name=name three
181+
swagger.docket.aaa.globalOperationParameters[0].description=some description three override
182+
swagger.docket.aaa.globalOperationParameters[0].modelRef=string
183+
swagger.docket.aaa.globalOperationParameters[0].parameterType=header
147184

148185
swagger.docket.bbb.title=group-bbb
149186
swagger.docket.bbb.basePackage=com.yonghui
150187
```
151188

152-
说明：默认配置与分组配置可以一起使用。在分组配置中没有配置的内容将使用默认配置替代，所以默认配置可以作为分组配置公共部分属性的配置。
189+
说明：默认配置与分组配置可以一起使用。在分组配置中没有配置的内容将使用默认配置替代，所以默认配置可以作为分组配置公共部分属性的配置。`swagger.docket.aaa.globalOperationParameters[0].name`会覆盖同名的全局配置。
153190

154191
### JSR-303校验注解支持
155192

‎pom.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
<groupId>com.didispace</groupId>
88
<artifactId>spring-boot-starter-swagger</artifactId>
9-
<version>1.3.0.RELEASE</version>
9+
<version>1.4.0.RELEASE</version>
1010

1111
<name>spring-boot-starter-swagger</name>
1212
<url>https://github.com/dyc87112/spring-boot-starter-swagger</url>

‎src/main/java/com/didispace/swagger/EnableSwagger2Doc.java

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
package com.didispace.swagger;
22

33
import org.springframework.context.annotation.Import;
4-
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
5-
import springfox.documentation.swagger2.annotations.EnableSwagger2;
64

75
import java.lang.annotation.*;
86

@@ -15,8 +13,7 @@
1513
@Retention(RetentionPolicy.RUNTIME)
1614
@Documented
1715
@Inherited
18-
@EnableSwagger2
19-
@Import({SwaggerAutoConfiguration.class, BeanValidatorPluginsConfiguration.class})
16+
@Import({SwaggerAutoConfiguration.class})
2017
public @interface EnableSwagger2Doc {
2118

2219

‎src/main/java/com/didispace/swagger/Swagger2Configuration.java

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
package com.didispace.swagger;
2+
3+
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
4+
import org.springframework.context.annotation.Configuration;
5+
import org.springframework.context.annotation.Import;
6+
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
7+
import springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration;
8+
9+
/**
10+
* @author 翟永超
11+
* Create Date： 2017/9/7.
12+
* My blog： http://blog.didispace.com
13+
*/
14+
@Configuration
15+
@ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true)
16+
@Import({
17+
Swagger2DocumentationConfiguration.class,
18+
BeanValidatorPluginsConfiguration.class
19+
})
20+
public class Swagger2Configuration {
21+
}

‎src/main/java/com/didispace/swagger/SwaggerAutoConfiguration.java

Lines changed: 74 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,31 +2,42 @@
22

33
import com.google.common.base.Predicate;
44
import com.google.common.base.Predicates;
5+
import com.google.common.collect.Lists;
56
import org.springframework.beans.BeansException;
67
import org.springframework.beans.factory.BeanFactory;
78
import org.springframework.beans.factory.BeanFactoryAware;
89
import org.springframework.beans.factory.config.ConfigurableBeanFactory;
910
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
11+
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
1012
import org.springframework.context.annotation.Bean;
1113
import org.springframework.context.annotation.Configuration;
14+
import org.springframework.context.annotation.Import;
1215
import springfox.documentation.builders.ApiInfoBuilder;
16+
import springfox.documentation.builders.ParameterBuilder;
1317
import springfox.documentation.builders.PathSelectors;
1418
import springfox.documentation.builders.RequestHandlerSelectors;
19+
import springfox.documentation.schema.ModelRef;
1520
import springfox.documentation.service.ApiInfo;
1621
import springfox.documentation.service.Contact;
22+
import springfox.documentation.service.Parameter;
1723
import springfox.documentation.spi.DocumentationType;
1824
import springfox.documentation.spring.web.plugins.Docket;
1925

2026
import java.util.ArrayList;
2127
import java.util.LinkedList;
2228
import java.util.List;
29+
import java.util.Set;
30+
import java.util.stream.Collectors;
2331

2432
/**
2533
* @author 翟永超
26-
* Create date ：2017/8/7.
34+
* Create date：2017/8/7.
2735
* My blog： http://blog.didispace.com
2836
*/
2937
@Configuration
38+
@Import({
39+
Swagger2Configuration.class
40+
})
3041
public class SwaggerAutoConfiguration implements BeanFactoryAware {
3142

3243
private BeanFactory beanFactory;
@@ -39,11 +50,12 @@ public SwaggerProperties swaggerProperties() {
3950

4051
@Bean
4152
@ConditionalOnMissingBean
53+
@ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true)
4254
public List<Docket> createRestApi(SwaggerProperties swaggerProperties) {
4355
ConfigurableBeanFactory configurableBeanFactory = (ConfigurableBeanFactory) beanFactory;
4456

4557
// 没有分组
46-
if(swaggerProperties.getDocket().size() == 0) {
58+
if (swaggerProperties.getDocket().size() == 0) {
4759
ApiInfo apiInfo = new ApiInfoBuilder()
4860
.title(swaggerProperties.getTitle())
4961
.description(swaggerProperties.getDescription())
@@ -58,23 +70,26 @@ public List<Docket> createRestApi(SwaggerProperties swaggerProperties) {
5870

5971
// base-path处理
6072
// 当没有配置任何path的时候，解析/**
61-
if(swaggerProperties.getBasePath().isEmpty()) {
73+
if (swaggerProperties.getBasePath().isEmpty()) {
6274
swaggerProperties.getBasePath().add("/**");
6375
}
6476
List<Predicate<String>> basePath = new ArrayList();
65-
for(String path : swaggerProperties.getBasePath()) {
77+
for (String path : swaggerProperties.getBasePath()) {
6678
basePath.add(PathSelectors.ant(path));
6779
}
6880

6981
// exclude-path处理
7082
List<Predicate<String>> excludePath = new ArrayList();
71-
for(String path : swaggerProperties.getExcludePath()) {
83+
for (String path : swaggerProperties.getExcludePath()) {
7284
excludePath.add(PathSelectors.ant(path));
7385
}
7486

87+
7588
Docket docket = new Docket(DocumentationType.SWAGGER_2)
7689
.host(swaggerProperties.getHost())
7790
.apiInfo(apiInfo)
91+
.globalOperationParameters(buildGlobalOperationParametersFromSwaggerProperties(
92+
swaggerProperties.getGlobalOperationParameters()))
7893
.select()
7994
.apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
8095
.paths(
@@ -91,7 +106,7 @@ public List<Docket> createRestApi(SwaggerProperties swaggerProperties) {
91106

92107
// 分组创建
93108
List<Docket> docketList = new LinkedList<>();
94-
for(String groupName : swaggerProperties.getDocket().keySet()) {
109+
for (String groupName : swaggerProperties.getDocket().keySet()) {
95110
SwaggerProperties.DocketInfo docketInfo = swaggerProperties.getDocket().get(groupName);
96111

97112
ApiInfo apiInfo = new ApiInfoBuilder()
@@ -102,33 +117,35 @@ public List<Docket> createRestApi(SwaggerProperties swaggerProperties) {
102117
.licenseUrl(docketInfo.getLicenseUrl().isEmpty() ? swaggerProperties.getLicenseUrl() : docketInfo.getLicenseUrl())
103118
.contact(
104119
new Contact(
105-
docketInfo.getContact().getName().isEmpty() ? swaggerProperties.getContact().getName() : docketInfo.getContact().getName(),
106-
docketInfo.getContact().getUrl().isEmpty() ? swaggerProperties.getContact().getUrl() : docketInfo.getContact().getUrl(),
107-
docketInfo.getContact().getEmail().isEmpty() ? swaggerProperties.getContact().getEmail() : docketInfo.getContact().getEmail()
120+
docketInfo.getContact().getName().isEmpty() ? swaggerProperties.getContact().getName() : docketInfo.getContact().getName(),
121+
docketInfo.getContact().getUrl().isEmpty() ? swaggerProperties.getContact().getUrl() : docketInfo.getContact().getUrl(),
122+
docketInfo.getContact().getEmail().isEmpty() ? swaggerProperties.getContact().getEmail() : docketInfo.getContact().getEmail()
108123
)
109124
)
110125
.termsOfServiceUrl(docketInfo.getTermsOfServiceUrl().isEmpty() ? swaggerProperties.getTermsOfServiceUrl() : docketInfo.getTermsOfServiceUrl())
111126
.build();
112127

113128
// base-path处理
114129
// 当没有配置任何path的时候，解析/**
115-
if(docketInfo.getBasePath().isEmpty()) {
130+
if (docketInfo.getBasePath().isEmpty()) {
116131
docketInfo.getBasePath().add("/**");
117132
}
118133
List<Predicate<String>> basePath = new ArrayList();
119-
for(String path : docketInfo.getBasePath()) {
134+
for (String path : docketInfo.getBasePath()) {
120135
basePath.add(PathSelectors.ant(path));
121136
}
122137

123138
// exclude-path处理
124139
List<Predicate<String>> excludePath = new ArrayList();
125-
for(String path : docketInfo.getExcludePath()) {
140+
for (String path : docketInfo.getExcludePath()) {
126141
excludePath.add(PathSelectors.ant(path));
127142
}
128143

129144
Docket docket = new Docket(DocumentationType.SWAGGER_2)
130145
.host(swaggerProperties.getHost())
131146
.apiInfo(apiInfo)
147+
.globalOperationParameters(assemblyGlobalOperationParameters(swaggerProperties.getGlobalOperationParameters(),
148+
docketInfo.getGlobalOperationParameters()))
132149
.groupName(groupName)
133150
.select()
134151
.apis(RequestHandlerSelectors.basePackage(docketInfo.getBasePackage()))
@@ -150,4 +167,49 @@ public List<Docket> createRestApi(SwaggerProperties swaggerProperties) {
150167
public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
151168
this.beanFactory = beanFactory;
152169
}
170+
171+
private List<Parameter> buildGlobalOperationParametersFromSwaggerProperties(
172+
List<SwaggerProperties.GlobalOperationParameter> globalOperationParameters) {
173+
List<Parameter> parameters = Lists.newArrayList();
174+
for (SwaggerProperties.GlobalOperationParameter globalOperationParameter : globalOperationParameters) {
175+
parameters.add(new ParameterBuilder()
176+
.name(globalOperationParameter.getName())
177+
.description(globalOperationParameter.getDescription())
178+
.modelRef(new ModelRef(globalOperationParameter.getModelRef()))
179+
.parameterType(globalOperationParameter.getParameterType())
180+
.required(Boolean.parseBoolean(globalOperationParameter.getRequired()))
181+
.build());
182+
}
183+
return parameters;
184+
}
185+
186+
/**
187+
* 局部参数按照name覆盖局部参数
188+
*
189+
* @param globalOperationParameters
190+
* @param docketOperationParameters
191+
* @return
192+
*/
193+
private List<Parameter> assemblyGlobalOperationParameters(
194+
List<SwaggerProperties.GlobalOperationParameter> globalOperationParameters,
195+
List<SwaggerProperties.GlobalOperationParameter> docketOperationParameters) {
196+
197+
if (docketOperationParameters == null || docketOperationParameters.isEmpty()) {
198+
return buildGlobalOperationParametersFromSwaggerProperties(globalOperationParameters);
199+
}
200+
201+
Set<String> docketNames = docketOperationParameters.stream()
202+
.map(SwaggerProperties.GlobalOperationParameter::getName)
203+
.collect(Collectors.toSet());
204+
205+
List<SwaggerProperties.GlobalOperationParameter> resultOperationParameters = Lists.newArrayList();
206+
207+
for (SwaggerProperties.GlobalOperationParameter parameter : globalOperationParameters) {
208+
if (!docketNames.contains(parameter.getName())) {
209+
resultOperationParameters.add(parameter);
210+
}
211+
}
212+
resultOperationParameters.addAll(docketOperationParameters);
213+
return buildGlobalOperationParametersFromSwaggerProperties(resultOperationParameters);
214+
}
153215
}

0 commit comments

Comments
 (0)