Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。
官网地址：swagger.io
SpringBoot集成swagger
swagger有swagger2和swagger3两个版本，两个版本引入的依赖不同，展示的UI界面也不同，本文以swagger2为例。
- 引入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>
- 新建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();
}
}
- 添加API接口说明
swagger api所使用到的注解及其作用如下所示。
| 注解 | 使用位置 | 作用 |
|---|
| @Api(tags = {“用户接口”}) | controller类 | 接口分组说明 | | @ApiOperation(“更新用户启停状态”) | 请求接口方法 | 方法作用说明 | | @ApiParam(“用户ID”) | 针对方法的单个参数 | 参数说明 | | @ApiModel | 针对方法的实体参数，在实体类上增加此注解 | 实体说明 | | @ApiModelProperty(“主键ID”) | 实体类的属性 | 属性字段作用说明 |
- 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>
或者引入新版本的knife4j：
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>${knife4j.version}</version>
</dependency>
优化前swagger访问地址：http://ip:port/swagger-ui.html#/
优化后swagger访问地址：http://ip:port/doc.html#/
- 部署不同环境如何关闭swagger
针对prod生产环境如何关闭swagger api访问呢？
- 方法一：可以使用注解@Profile判断配置文件，如果不是prod则启用，否则默认启用swagger，代码如下。
@Configuration
@EnableSwagger2
@Profile("!prod")
public class Swagger2Config {
...
}
- 方法二：在config类配置注解
@ConditionalOnProperty
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
在prod yaml配置文件中增加swagger开关，当值为true时为开启。
swagger：
enable: false
|