Skip to content

Commit 41da604

Browse files
dyc87112dyc87112
committed
init
1 parent c18875e commit 41da604

File tree

5 files changed

+277
-1
lines changed

5 files changed

+277
-1
lines changed

‎README.md‎

Lines changed: 52 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,53 @@
11
# spring-boot-starter-swagger
2-
spring boot starter for swagger 2.x
2+
3+
该项目主要利用Spring Boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成API文档。
4+
5+
# 如何使用
6+
7+
在该项目的帮助下，我们的Spring Boot可以轻松的引入swagger2，主需要做下面两个步骤：
8+
9+
- 在`pom.xml`中引入依赖：
10+
11+
```xml
12+
<dependency>
13+
<groupId>com.didispace</groupId>
14+
<artifactId>spring-boot-starter-swagger</artifactId>
15+
<version>1.0.0.RELEASE</version>
16+
</dependency>
17+
```
18+
19+
- 在应用主类中增加`@EnableSwagger2Doc`注解
20+
21+
```java
22+
@EnableSwagger2Doc
23+
@SpringBootApplication
24+
public class Bootstrap {
25+
26+
public static void main(String[] args) {
27+
SpringApplication.run(Bootstrap.class, args);
28+
}
29+
30+
}
31+
```
32+
33+
默认情况下就能产生所有Spring MVC加载的请求文档了。
34+
35+
# 参数配置
36+
37+
更细致的配置文档内容，可以参考如下参数：
38+
39+
```properties
40+
swagger.title=标题
41+
swagger.description=描述
42+
swagger.version=版本
43+
swagger.license=许可证
44+
swagger.licenseUrl=许可证URL
45+
swagger.termsOfServiceUrl=服务条款URL
46+
swagger.contact.name=维护人
47+
swagger.contact.url=维护人URL
48+
swagger.contact.email=维护人email
49+
swagger.base-path=产生文档的基础URL规则，默认：/**
50+
swagger.exclude-path=需要排除的URL规则，默认为空
51+
```
52+
53+
`swagger.base-path`和`swagger.exclude-path`使用ANT规则配置

‎pom.xml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
7+
<groupId>com.didispace</groupId>
8+
<artifactId>spring-boot-starter-swagger</artifactId>
9+
<version>1.0.0.RELEASE</version>
10+
11+
<properties>
12+
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
13+
<version.java>1.8</version.java>
14+
<version.swagger>2.7.0</version.swagger>
15+
<version.spring-boot>1.5.6.RELEASE</version.spring-boot>
16+
</properties>
17+
18+
<dependencies>
19+
<dependency>
20+
<groupId>org.springframework.boot</groupId>
21+
<artifactId>spring-boot-starter</artifactId>
22+
<optional>true</optional>
23+
</dependency>
24+
<dependency>
25+
<groupId>org.springframework.boot</groupId>
26+
<artifactId>spring-boot-configuration-processor</artifactId>
27+
<optional>true</optional>
28+
</dependency>
29+
<dependency>
30+
<groupId>io.springfox</groupId>
31+
<artifactId>springfox-swagger-ui</artifactId>
32+
<version>${version.swagger}</version>
33+
</dependency>
34+
<dependency>
35+
<groupId>io.springfox</groupId>
36+
<artifactId>springfox-swagger2</artifactId>
37+
<version>${version.swagger}</version>
38+
</dependency>
39+
<dependency>
40+
<groupId>org.projectlombok</groupId>
41+
<artifactId>lombok</artifactId>
42+
<version>1.16.12</version>
43+
<scope>provided</scope>
44+
</dependency>
45+
</dependencies>
46+
47+
<dependencyManagement>
48+
<dependencies>
49+
<dependency>
50+
<groupId>org.springframework.boot</groupId>
51+
<artifactId>spring-boot-dependencies</artifactId>
52+
<version>${version.spring-boot}</version>
53+
<type>pom</type>
54+
<scope>import</scope>
55+
</dependency>
56+
</dependencies>
57+
</dependencyManagement>
58+
59+
<build>
60+
<plugins>
61+
<plugin>
62+
<groupId>org.apache.maven.plugins</groupId>
63+
<artifactId>maven-compiler-plugin</artifactId>
64+
<version>3.3</version>
65+
<configuration>
66+
<encoding>${project.build.sourceEncoding}</encoding>
67+
<source>${version.java}</source>
68+
<target>${version.java}</target>
69+
<showWarnings>true</showWarnings>
70+
</configuration>
71+
</plugin>
72+
</plugins>
73+
</build>
74+
</project>

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
package com.didispace.swagger;
2+
3+
import org.springframework.context.annotation.Import;
4+
import springfox.documentation.swagger2.annotations.EnableSwagger2;
5+
6+
import java.lang.annotation.*;
7+
8+
/**
9+
* @author 翟永超
10+
* @create 2017/8/7.
11+
* @blog http://blog.didispace.com
12+
*/
13+
@Target({ElementType.TYPE})
14+
@Retention(RetentionPolicy.RUNTIME)
15+
@Documented
16+
@Inherited
17+
@EnableSwagger2
18+
@Import(SwaggerAutoConfiguration.class)
19+
public @interface EnableSwagger2Doc {
20+
21+
22+
}

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

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
package com.didispace.swagger;
2+
3+
import com.google.common.base.Predicate;
4+
import com.google.common.base.Predicates;
5+
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
6+
import org.springframework.context.annotation.Bean;
7+
import org.springframework.context.annotation.Configuration;
8+
import springfox.documentation.builders.ApiInfoBuilder;
9+
import springfox.documentation.builders.PathSelectors;
10+
import springfox.documentation.service.ApiInfo;
11+
import springfox.documentation.service.Contact;
12+
import springfox.documentation.spi.DocumentationType;
13+
import springfox.documentation.spring.web.plugins.Docket;
14+
15+
import java.util.ArrayList;
16+
import java.util.List;
17+
18+
/**
19+
* @author 翟永超
20+
* @create 2017/8/7.
21+
* @blog http://blog.didispace.com
22+
*/
23+
@Configuration
24+
public class SwaggerAutoConfiguration {
25+
26+
@Bean
27+
@ConditionalOnMissingBean
28+
public SwaggerProperties swaggerProperties() {
29+
return new SwaggerProperties();
30+
}
31+
32+
@Bean
33+
@ConditionalOnMissingBean
34+
public Docket createRestApi(SwaggerProperties swaggerProperties) {
35+
ApiInfo apiInfo = new ApiInfoBuilder()
36+
.title(swaggerProperties.getTitle())
37+
.description(swaggerProperties.getDescription())
38+
.version(swaggerProperties.getVersion())
39+
.license(swaggerProperties.getLicense())
40+
.licenseUrl(swaggerProperties.getLicenseUrl())
41+
.contact(new Contact(swaggerProperties.getContact().getName(),
42+
swaggerProperties.getContact().getUrl(),
43+
swaggerProperties.getContact().getEmail()))
44+
.termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
45+
.build();
46+
47+
// 当没有配置任何path的时候，解析/**
48+
if(swaggerProperties.getBasePath().isEmpty()) {
49+
swaggerProperties.getBasePath().add("/**");
50+
}
51+
52+
List<Predicate<String>> basePath = new ArrayList();
53+
for(String path : swaggerProperties.getBasePath()) {
54+
basePath.add(PathSelectors.ant(path));
55+
}
56+
57+
List<Predicate<String>> excludePath = new ArrayList();
58+
for(String path : swaggerProperties.getExcludePath()) {
59+
excludePath.add(PathSelectors.ant(path));
60+
}
61+
62+
return new Docket(DocumentationType.SWAGGER_2)
63+
.apiInfo(apiInfo)
64+
.select()
65+
.paths(
66+
Predicates.and(
67+
Predicates.not(Predicates.or(excludePath)),
68+
Predicates.or(basePath)
69+
)
70+
)
71+
.build();
72+
}
73+
74+
}

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

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
package com.didispace.swagger;
2+
3+
import lombok.Data;
4+
import lombok.NoArgsConstructor;
5+
import org.springframework.boot.context.properties.ConfigurationProperties;
6+
7+
import java.util.ArrayList;
8+
import java.util.List;
9+
10+
/**
11+
* @author 翟永超
12+
* @create 2017/8/7.
13+
* @blog http://blog.didispace.com
14+
*/
15+
@Data
16+
@ConfigurationProperties("swagger")
17+
public class SwaggerProperties {
18+
19+
/**标题**/
20+
private String title = "";
21+
/**描述**/
22+
private String description = "";
23+
/**版本**/
24+
private String version = "";
25+
/**许可证**/
26+
private String license = "";
27+
/**许可证URL**/
28+
private String licenseUrl = "";
29+
/**服务条款URL**/
30+
private String termsOfServiceUrl = "";
31+
32+
private Contact contact = new Contact();
33+
34+
/**swagger会解析的url规则**/
35+
private List<String> basePath = new ArrayList<>();
36+
/**在basePath基础上需要排除的url规则**/
37+
private List<String> excludePath = new ArrayList<>();
38+
39+
40+
@Data
41+
@NoArgsConstructor
42+
public static class Contact {
43+
44+
/**联系人**/
45+
private String name = "";
46+
/**联系人url**/
47+
private String url = "";
48+
/**联系人email**/
49+
private String email = "";
50+
51+
}
52+
53+
}
54+
55+

0 commit comments

Comments
 (0)