SpringBoot集成swagger

Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。
官网地址：swagger.io

SpringBoot集成swagger

swagger有swagger2和swagger3两个版本，两个版本引入的依赖不同，展示的UI界面也不同，本文以swagger2为例。

1. 引入swagger依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
1
2
3
4
5
6
7
8
9
10

2. 新建config类
   新建一个swagger的配置类，在该类上使用注解@EnableSwagger2即可开启swagger，此注解也可放在服务启动类上；

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.
                basePackage("com.test.manager.controller")).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Manage Swagger").description("管理系统OpenAPI").version("1.0").build();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

3. 添加API接口说明
   swagger api所使用到的注解及其作用如下所示。

4. UI优化
   swagger默认的UI不太符合大家的使用习惯，网上有一个优化swagger UI的开源项目，优化后的页面与postman类似。此项目GitHub开源地址：swagger-bootstrap-ui
   只需要引入一个依赖即可优化界面：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>
1
2
3
4
5

或者引入新版本的knife4j：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>${knife4j.version}</version>
</dependency>
1
2
3
4
5

优化前swagger访问地址：http://ip:port/swagger-ui.html#/
优化后swagger访问地址：http://ip:port/doc.html#/

5. 部署不同环境如何关闭swagger
   针对prod生产环境如何关闭swagger api访问呢？

• 方法一：可以使用注解@Profile判断配置文件，如果不是prod则启用，否则默认启用swagger，代码如下。

@Configuration
@EnableSwagger2
@Profile("!prod")
public class Swagger2Config {
    ...
}
1
2
3
4
5
6

• 方法二：在config类配置注解@ConditionalOnProperty

@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
1

在prod yaml配置文件中增加swagger开关，当值为true时为开启。

swagger：
  enable: false
1
2