Spring Boot 集成 swagger 3.0 指南
Spring Boot 集成 swagger 3.0 指南
- 一、Swagger介绍
- 1.springfox-swagger 2
- 2.SpringFox 3.0.0 发布
- 二、Spring Boot 集成 swagger 3.0
- 1. 添加Maven依赖
- 2. 创建配置类配置Swagger
- 2.1 创建SwaggerConfig 配置类
- 2.1 创建TestInfoConfig信息配置类
- 3. 在你的Controller上添加swagger注解
- 4. 如启用了访问权限，还需将swagger相关uri允许匿名访问
- 5. 启动与访问
一、Swagger介绍
- 号称世界上最流行的Api框架；
- Restful Api 文档在线自动生成工具=>Api文档与API定义同步更新
- 直接运行，可以在在线测试API 接口
- 支持多种语言：（java，Php…）
官网地址：https://swagger.io/
1.springfox-swagger 2
SpringBoot项目整合Swagger2需要用到两个依赖：springfox-swagger2和springfox-swagger-ui，用于自动生成swagger文档。
springfox-swagger2：这个组件的功能用于帮助我们自动生成描述API的json文件。springfox-swagger-ui：就是将描述API的json文件解析出来，用一种更友好的方式呈现出来。
2.SpringFox 3.0.0 发布
此版本的亮点：
- Spring5，Webflux支持（仅支持请求映射，尚不支持功能端点）。
- Spring Integration支持。
- SpringBoot支持springfox Boot starter依赖性（零配置、自动配置支持）。
- 支持OpenApi 3.0.3。
- 零依赖。几乎只需要spring-plugin，swagger-core ，现有的swagger2注释将继续工作并丰富openapi3.0规范。
兼容性说明：
- 需要Java 8
- 需要Spring5.x（未在早期版本中测试）
- 需要SpringBoot 2.2+（未在早期版本中测试）
注意：Swagger2.0和Swagger3.0有很多区别，下面使用的是Swagger3.0，有区别的地方会简单说明。
二、Spring Boot 集成 swagger 3.0
1. 添加Maven依赖
引入依赖springfox-boot-starter：
<!-- 引入Swagger3依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2. 创建配置类配置Swagger
自定义配置信息：
3.0版本在配置上与2.9稍有差别，包括依赖包改为: springfox-boot-starter，启用注解更改为: @EnableOpenApi等。
- Swagger3.0 注解：
@EnableOpenApi - Swagger2.0 注解：
@EnableSwagger2
2.1 创建SwaggerConfig 配置类
package com.test.web.core.config;
import java.util.ArrayList;
import java.util.List;
import io.swagger.annotations.Api;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.test.common.config.TestInfoConfig;
import io.swagger.annotations.ApiOperation;
import io.swagger.models.auth.In;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
/**
* Swagger3的接口配置
*
* @author fy
*/
@Configuration
//默认开启 可注释
//@EnableOpenApi
public class SwaggerConfig {
/**
* 系统基础配置 yml文件可配置读取
*/
@Autowired
private TestInfoConfig testInfoConfig;
/**
* 是否开启swagger
*/
@Value("${swagger.enabled}")
private boolean enabled;
/**
* 设置请求的统一前缀
*/
@Value("${swagger.pathMapping}")
private String pathMapping;
/**
* 创建API
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
// 使用 swagger 开关。默认 true
.enable(enabled)
// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.apiInfo(apiInfo())
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api，用这种方式更灵活
// 以 @ApiOperation 注解为依据进行扫描
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 以 @Api 注解为依据进行扫描
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
// 扫描指定包中的swagger注解
//.apis(RequestHandlerSelectors.basePackage("com.test.web"))
// 扫描所有
// .apis(RequestHandlerSelectors.any())
//过滤器：对外暴露所有 URI
.paths(PathSelectors.any())
//.paths(none()) // 过滤器：一个 URI 都不对外暴露
//.paths(ant()) // 过滤器：对外暴露符合 ANT 风格正则表达式的 URI
//.paths(regex() // 过滤器：对外暴露符合正则表达式的 URI
.build()
//设置安全模式，swagger可以设置访问token
.securitySchemes(securitySchemes())
.securityContexts(securityContexts());
// .pathMapping(pathMapping)
}
/**
* 安全模式，这里指定token通过Authorization头请求头传递
*/
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
return apiKeyList;
}
/**
* 安全上下文
*/
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.operationSelector(o -> o.requestMappingPattern().matches("/.*"))
.build());
return securityContexts;
}
/**
* 默认的安全上引用
*/
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
/**
* 添加摘要信息
*/
private ApiInfo apiInfo() {
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
// 设置标题
.title("Test API文档")
// 描述
.description("某物联网平台接口文档说明")
// 作者信息
.contact(new Contact(testInfoConfig.getName(), "http://aaaa.com", "ahsjda@163.com"))
// 版本
.version(testInfoConfig.getVersion())
.build();
}
}
2.1 创建TestInfoConfig信息配置类
package com.test.common.config;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
/**
* 读取项目相关配置
*
* @author fy
*/
@Component
@ConfigurationProperties(prefix = "test")
@Data
public class TestInfoConfig{
/**
* 项目名称
*/
private String name;
/**
* 版本
*/
private String version;
/**
* 版权年份
*/
private String copyrightYear;
}
TestInfoConfig Yml配置信息如下图所示：
3. 在你的Controller上添加swagger注解
4. 如启用了访问权限，还需将swagger相关uri允许匿名访问
具体需要添加的uri有：
/swagger**/**
/webjars/**
/v3/**
/doc.html
5. 启动与访问
启动应用，访问地址http://localhost:8080/swagger-ui/index.html
Swagger2.0 、Swagger3.0访问地址区别：
- Swagger3.0 访问地址：
http://localhost:8080/swagger-ui/index.html - Swagger2.0 访问地址：
http://localhost:8080/swagger-ui.html
