Skip to content

Commit 4bd4002

Browse files
committed
1.2.0.RELEASE 新增分组配置功能
1 parent b30b7e7 commit 4bd4002

File tree

5 files changed

+195
-45
lines changed

5 files changed

+195
-45
lines changed

README.md

Lines changed: 49 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
<dependency>
2424
<groupId>com.didispace</groupId>
2525
<artifactId>spring-boot-starter-swagger</artifactId>
26-
<version>1.1.0.RELEASE</version>
26+
<version>1.2.0.RELEASE</version>
2727
</dependency>
2828
```
2929

@@ -47,7 +47,7 @@ public class Bootstrap {
4747

4848
更细致的配置内容参考如下:
4949

50-
**配置示例**
50+
## 配置示例
5151

5252
```properties
5353
swagger.title=spring-boot-starter-swagger
@@ -56,15 +56,17 @@ swagger.version=1.1.0.RELEASE
5656
swagger.license=Apache License, Version 2.0
5757
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
5858
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
59-
swagger.contact.name=程序猿DD
59+
swagger.contact.name=didi
6060
swagger.contact.url=http://blog.didispace.com
6161
swagger.contact.email[email protected]
6262
swagger.base-package=com.didispace
6363
swagger.base-path=/**
6464
swagger.exclude-path=/error, /ops/**
6565
```
6666

67-
**配置说明**
67+
## 配置说明
68+
69+
### 默认配置
6870

6971
- swagger.title=标题
7072
- swagger.description=描述
@@ -79,7 +81,7 @@ swagger.exclude-path=/error, /ops/**
7981
- swagger.base-path=需要处理的基础URL规则,默认:/**
8082
- swagger.exclude-path=需要排除的URL规则,默认:空
8183

82-
## Path规则说明
84+
### Path规则说明
8385

8486
`swagger.base-path``swagger.exclude-path`使用ANT规则配置。
8587

@@ -96,4 +98,45 @@ swagger.exclude-path=/ops/**, /error
9698

9799
上面的设置将解析所有除了`/ops/`开始以及spring boot自带`/error`请求路径。
98100

99-
其中,`exclude-path`可以配合`management.context-path=/ops`设置的spring boot actuator的context-path来排除所有监控端点。
101+
其中,`exclude-path`可以配合`management.context-path=/ops`设置的spring boot actuator的context-path来排除所有监控端点。
102+
103+
### 分组配置
104+
105+
当我们一个项目的API非常多的时候,我们希望对API文档实现分组。从1.2.0.RELEASE开始,将支持分组配置功能。
106+
107+
![分组功能](https://github.com/dyc87112/spring-boot-starter-swagger/blob/master/images/swagger-group.png)
108+
109+
具体配置内容如下:
110+
111+
- swagger.docket.<name>.title=标题
112+
- swagger.docket.<name>.description=描述
113+
- swagger.docket.<name>.version=版本
114+
- swagger.docket.<name>.license=许可证
115+
- swagger.docket.<name>.licenseUrl=许可证URL
116+
- swagger.docket.<name>.termsOfServiceUrl=服务条款URL
117+
- swagger.docket.<name>.contact.name=维护人
118+
- swagger.docket.<name>.contact.url=维护人URL
119+
- swagger.docket.<name>.contact.email=维护人email
120+
- swagger.docket.<name>.base-package=swagger扫描的基础包,默认:全扫描
121+
- swagger.docket.<name>.base-path=需要处理的基础URL规则,默认:/**
122+
- swagger.docket.<name>.exclude-path=需要排除的URL规则,默认:空
123+
124+
说明:`<name>`为swagger文档的分组名称,同一个项目中可以配置多个分组,用来划分不同的API文档。
125+
126+
**分组配置示例**
127+
128+
```properties
129+
swagger.docket.aaa.title=group-a
130+
swagger.docket.aaa.description=Starter for swagger 2.x
131+
swagger.docket.aaa.version=1.2.0.RELEASE
132+
swagger.docket.aaa.termsOfServiceUrl=https://gitee.com/didispace/spring-boot-starter-swagger
133+
swagger.docket.aaa.contact.name=zhaiyongchao
134+
swagger.docket.aaa.contact.url=http://spring4all.com/
135+
swagger.docket.aaa.contact.email[email protected]
136+
swagger.docket.aaa.excludePath=/ops/**
137+
138+
swagger.docket.bbb.title=group-bbb
139+
swagger.docket.bbb.basePackage=com.yonghui
140+
```
141+
142+
说明:默认配置与分组配置可以一起使用。在分组配置中没有配置的内容将使用默认配置替代,所以默认配置可以作为分组配置公共部分属性的配置。

images/swagger-group.png

35.7 KB
Loading

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.1.0.RELEASE</version>
9+
<version>1.2.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/SwaggerAutoConfiguration.java

Lines changed: 112 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@
22

33
import com.google.common.base.Predicate;
44
import com.google.common.base.Predicates;
5+
import org.springframework.beans.BeansException;
6+
import org.springframework.beans.factory.BeanFactory;
7+
import org.springframework.beans.factory.BeanFactoryAware;
8+
import org.springframework.beans.factory.config.ConfigurableBeanFactory;
59
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
610
import org.springframework.context.annotation.Bean;
711
import org.springframework.context.annotation.Configuration;
@@ -14,6 +18,7 @@
1418
import springfox.documentation.spring.web.plugins.Docket;
1519

1620
import java.util.ArrayList;
21+
import java.util.LinkedList;
1722
import java.util.List;
1823

1924
/**
@@ -22,7 +27,9 @@
2227
* My blog: http://blog.didispace.com
2328
*/
2429
@Configuration
25-
public class SwaggerAutoConfiguration {
30+
public class SwaggerAutoConfiguration implements BeanFactoryAware {
31+
32+
private BeanFactory beanFactory;
2633

2734
@Bean
2835
@ConditionalOnMissingBean
@@ -32,46 +39,113 @@ public SwaggerProperties swaggerProperties() {
3239

3340
@Bean
3441
@ConditionalOnMissingBean
35-
public Docket createRestApi(SwaggerProperties swaggerProperties) {
36-
ApiInfo apiInfo = new ApiInfoBuilder()
37-
.title(swaggerProperties.getTitle())
38-
.description(swaggerProperties.getDescription())
39-
.version(swaggerProperties.getVersion())
40-
.license(swaggerProperties.getLicense())
41-
.licenseUrl(swaggerProperties.getLicenseUrl())
42-
.contact(new Contact(swaggerProperties.getContact().getName(),
43-
swaggerProperties.getContact().getUrl(),
44-
swaggerProperties.getContact().getEmail()))
45-
.termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
46-
.build();
47-
48-
// base-path处理
49-
// 当没有配置任何path的时候,解析/**
50-
if(swaggerProperties.getBasePath().isEmpty()) {
51-
swaggerProperties.getBasePath().add("/**");
52-
}
53-
List<Predicate<String>> basePath = new ArrayList();
54-
for(String path : swaggerProperties.getBasePath()) {
55-
basePath.add(PathSelectors.ant(path));
56-
}
42+
public List<Docket> createRestApi(SwaggerProperties swaggerProperties) {
43+
ConfigurableBeanFactory configurableBeanFactory = (ConfigurableBeanFactory) beanFactory;
44+
45+
// 没有分组
46+
if(swaggerProperties.getDocket().size() == 0) {
47+
ApiInfo apiInfo = new ApiInfoBuilder()
48+
.title(swaggerProperties.getTitle())
49+
.description(swaggerProperties.getDescription())
50+
.version(swaggerProperties.getVersion())
51+
.license(swaggerProperties.getLicense())
52+
.licenseUrl(swaggerProperties.getLicenseUrl())
53+
.contact(new Contact(swaggerProperties.getContact().getName(),
54+
swaggerProperties.getContact().getUrl(),
55+
swaggerProperties.getContact().getEmail()))
56+
.termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
57+
.build();
58+
59+
// base-path处理
60+
// 当没有配置任何path的时候,解析/**
61+
if(swaggerProperties.getBasePath().isEmpty()) {
62+
swaggerProperties.getBasePath().add("/**");
63+
}
64+
List<Predicate<String>> basePath = new ArrayList();
65+
for(String path : swaggerProperties.getBasePath()) {
66+
basePath.add(PathSelectors.ant(path));
67+
}
68+
69+
// exclude-path处理
70+
List<Predicate<String>> excludePath = new ArrayList();
71+
for(String path : swaggerProperties.getExcludePath()) {
72+
excludePath.add(PathSelectors.ant(path));
73+
}
74+
75+
Docket docket = new Docket(DocumentationType.SWAGGER_2)
76+
.apiInfo(apiInfo)
77+
.select()
78+
.apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
79+
.paths(
80+
Predicates.and(
81+
Predicates.not(Predicates.or(excludePath)),
82+
Predicates.or(basePath)
83+
)
84+
)
85+
.build();
5786

58-
// exclude-path处理
59-
List<Predicate<String>> excludePath = new ArrayList();
60-
for(String path : swaggerProperties.getExcludePath()) {
61-
excludePath.add(PathSelectors.ant(path));
87+
configurableBeanFactory.registerSingleton("defaultDocket", docket);
88+
return null;
6289
}
6390

64-
return new Docket(DocumentationType.SWAGGER_2)
65-
.apiInfo(apiInfo)
66-
.select()
67-
.apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()))
68-
.paths(
69-
Predicates.and(
70-
Predicates.not(Predicates.or(excludePath)),
71-
Predicates.or(basePath)
72-
)
73-
)
74-
.build();
91+
// 分组创建
92+
List<Docket> docketList = new LinkedList<>();
93+
for(String groupName : swaggerProperties.getDocket().keySet()) {
94+
SwaggerProperties.DocketInfo docketInfo = swaggerProperties.getDocket().get(groupName);
95+
96+
ApiInfo apiInfo = new ApiInfoBuilder()
97+
.title(docketInfo.getTitle().isEmpty() ? swaggerProperties.getTitle() : docketInfo.getTitle())
98+
.description(docketInfo.getDescription().isEmpty() ? swaggerProperties.getDescription() : docketInfo.getDescription())
99+
.version(docketInfo.getVersion().isEmpty() ? swaggerProperties.getVersion() : docketInfo.getVersion())
100+
.license(docketInfo.getLicense().isEmpty() ? swaggerProperties.getLicense() : docketInfo.getLicense())
101+
.licenseUrl(docketInfo.getLicenseUrl().isEmpty() ? swaggerProperties.getLicenseUrl() : docketInfo.getLicenseUrl())
102+
.contact(
103+
new Contact(
104+
docketInfo.getContact().getName().isEmpty() ? swaggerProperties.getContact().getName() : docketInfo.getContact().getName(),
105+
docketInfo.getContact().getUrl().isEmpty() ? swaggerProperties.getContact().getUrl() : docketInfo.getContact().getUrl(),
106+
docketInfo.getContact().getEmail().isEmpty() ? swaggerProperties.getContact().getEmail() : docketInfo.getContact().getEmail()
107+
)
108+
)
109+
.termsOfServiceUrl(docketInfo.getTermsOfServiceUrl().isEmpty() ? swaggerProperties.getTermsOfServiceUrl() : docketInfo.getTermsOfServiceUrl())
110+
.build();
111+
112+
// base-path处理
113+
// 当没有配置任何path的时候,解析/**
114+
if(docketInfo.getBasePath().isEmpty()) {
115+
docketInfo.getBasePath().add("/**");
116+
}
117+
List<Predicate<String>> basePath = new ArrayList();
118+
for(String path : docketInfo.getBasePath()) {
119+
basePath.add(PathSelectors.ant(path));
120+
}
121+
122+
// exclude-path处理
123+
List<Predicate<String>> excludePath = new ArrayList();
124+
for(String path : docketInfo.getExcludePath()) {
125+
excludePath.add(PathSelectors.ant(path));
126+
}
127+
128+
Docket docket = new Docket(DocumentationType.SWAGGER_2)
129+
.apiInfo(apiInfo)
130+
.groupName(groupName)
131+
.select()
132+
.apis(RequestHandlerSelectors.basePackage(docketInfo.getBasePackage()))
133+
.paths(
134+
Predicates.and(
135+
Predicates.not(Predicates.or(excludePath)),
136+
Predicates.or(basePath)
137+
)
138+
)
139+
.build();
140+
141+
configurableBeanFactory.registerSingleton(groupName, docket);
142+
docketList.add(docket);
143+
}
144+
return docketList;
75145
}
76146

147+
@Override
148+
public void setBeanFactory(BeanFactory beanFactory) throws BeansException {
149+
this.beanFactory = beanFactory;
150+
}
77151
}

src/main/java/com/didispace/swagger/SwaggerProperties.java

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@
55
import org.springframework.boot.context.properties.ConfigurationProperties;
66

77
import java.util.ArrayList;
8+
import java.util.LinkedHashMap;
89
import java.util.List;
10+
import java.util.Map;
911

1012
/**
1113
* @author 翟永超
@@ -39,6 +41,37 @@ public class SwaggerProperties {
3941
/**在basePath基础上需要排除的url规则**/
4042
private List<String> excludePath = new ArrayList<>();
4143

44+
/**分组文档**/
45+
private Map<String, DocketInfo> docket = new LinkedHashMap<>();
46+
47+
@Data
48+
@NoArgsConstructor
49+
public static class DocketInfo {
50+
51+
/**标题**/
52+
private String title = "";
53+
/**描述**/
54+
private String description = "";
55+
/**版本**/
56+
private String version = "";
57+
/**许可证**/
58+
private String license = "";
59+
/**许可证URL**/
60+
private String licenseUrl = "";
61+
/**服务条款URL**/
62+
private String termsOfServiceUrl = "";
63+
64+
private Contact contact = new Contact();
65+
66+
/**swagger会解析的包路径**/
67+
private String basePackage = "";
68+
69+
/**swagger会解析的url规则**/
70+
private List<String> basePath = new ArrayList<>();
71+
/**在basePath基础上需要排除的url规则**/
72+
private List<String> excludePath = new ArrayList<>();
73+
74+
}
4275

4376
@Data
4477
@NoArgsConstructor

0 commit comments

Comments
 (0)