springcloud-gateway整合swagger

# 版本和说明

swagger:3.0.0
gateway微服务的使用方式和单应用没啥区别，只是多了设置右上角模块的操作。
以下操作基于你已经搭建成功的服务，只讲怎么添加swagger3

# 单应用

# pom添加

<!-- 3.0版本只需要引入一个，不再像2.x版本需要引入两个包 -->
<dependency>
	<groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>${swagger.version}</version>
</dependency>

1
2
3
4
5
6
7

# 配置文件

/**
 * swagger配制
 *
 * @author teler
 * @date 2020-12-30
 */
@Configuration
public class SwaggerConfig {

	@Value("${swagger.enable:true}")
	private Boolean enable;

	@Bean
	public Docket api() {
		return new Docket(DocumentationType.OAS_30)
					   //资源
				       .globalResponses(HttpMethod.GET, new ArrayList<>())
				       .globalResponses(HttpMethod.PUT, new ArrayList<>())
				       .globalResponses(HttpMethod.POST, new ArrayList<>())
				       .globalResponses(HttpMethod.DELETE, new ArrayList<>())
					   //是否启动
				       .enable(enable)
					   //头部信息
				       .apiInfo(apiInfo())
				       .select()
				       /**
				        * RequestHandlerSelectors,配置要扫描接口的方式
				        * basePackage指定要扫描的包
				        * any()扫描所有，项目中的所有接口都会被扫描到
				        * none()不扫描
				        * withClassAnnotation()扫描类上的注解
				        * withMethodAnnotation()扫描方法上的注解
				        */
				       .apis(RequestHandlerSelectors.any())
					   //过滤某个路径
				       .paths(PathSelectors.any())
				       .build()
					   //协议
				       .protocols(newHashSet("https", "http"))
				       .securitySchemes(securitySchemes())
				       .securityContexts(securityContexts());
	}


	/**
	 * API 页面上半部分展示信息
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				       .title("接口文档")
				       .description("@author Teler")
				       .contact(new Contact("Teler", null, "teler96@qq.com"))
				       .version("1.0")
				       .build();
	}

	/**
	 * 设置接口单独的授权信息
	 */
	private List<SecurityScheme> securitySchemes() {
		return Collections.singletonList(new ApiKey("BASE_TOKEN", "token", "header"));
	}

	/**
	 * 授权信息全局应用
	 */
	private List<SecurityContext> securityContexts() {
		return Collections.singletonList(
				SecurityContext.builder()
						.securityReferences(
								Collections.singletonList(new SecurityReference("BASE_TOKEN",
										new AuthorizationScope[]{new AuthorizationScope("global", "")}
								)))
						//.forPaths(PathSelectors.any())
						.build()
		);
	}

	@SafeVarargs
	private final <T> Set<T> newHashSet(T... ts) {
		if (ts.length > 0) {
			return new LinkedHashSet<>(Arrays.asList(ts));
		}
		return null;
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

# 访问

到这一步我们应该就能正常访问swagger文档了，但是要注意3.0的访问页面路径有所变化

http://ip:port/swagger-ui/

# 页面

在这里插入图片描述

# 微服务

gateway版本:2.2.5

# 添加文件

MySwaggerResourcesProvider在gateway模块中创建，注意其中的一些注解和说明，否则应用无法正常启动

# MySwaggerResourcesProvider

@Primary这个注解是告诉spring 如果有冲突优先使用当前类没有这个会报实现类冲突看源码能发现SwaggerResourcesProvider已经有一个InMemorySwaggerResourcesProvider实现类但是自带的不能满足我们的要求

/**
 * swagger的配置类
 *
 * @author teler
 */
@Component
@Primary
public class MySwaggerResourcesProvider implements SwaggerResourcesProvider {

	/**
	 * swagger3默认的url后缀
	 */
	private static final String SWAGGER2URL = "/v3/api-docs";
	/**
	 * 网关路由
	 */
	private final RouteLocator routeLocator;

	/**
	 * 网关应用名称
	 */
	@Value("${spring.application.name}")
	private String self;

	@Autowired
	public MySwaggerResourcesProvider(RouteLocator routeLocator) {
		this.routeLocator = routeLocator;
	}

	/**
	 * 对于gateway来说这块比较重要 让swagger能找到对应的服务
	 *
	 * @return
	 */
	@Override
	public List<SwaggerResource> get() {
		List<SwaggerResource> resources = new ArrayList<>();
		List<String> routeHosts = new ArrayList<>();
		// 获取所有可用的host：serviceId
		routeLocator.getRoutes().filter(route -> route.getUri().getHost() != null)
				.filter(route -> !self.equals(route.getUri().getHost()))
				.subscribe(route -> routeHosts.add(route.getUri().getHost()));

		// 记录已经添加过的server
		Set<String> dealed = new HashSet<>();
		routeHosts.forEach(instance -> {
			// 拼接url
			String url = "/" + instance.toLowerCase() + SWAGGER2URL;
			if (!dealed.contains(url)) {
				dealed.add(url);
				SwaggerResource swaggerResource = new SwaggerResource();
				swaggerResource.setUrl(url);
				swaggerResource.setName(instance);
				resources.add(swaggerResource);
			}
		});
		return resources;
	}
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60