集成SPRINGDOCOPENAPI的微服务实践-springcloud⼊门教程
在⽂章中我们学习了使⽤swagger2来⽣成微服务的⽂档⽅法。但SpringFox 库最重要的问题是缺乏对最新版本 3 中的 OpenAPI 和 Spring
的⽀持使⽤ WebFlux 构建的反应式 API。所有这些特性都是由Springdoc OpenAPI 库实现的。因此，它可能会取代 SpringFox 作为Swagger 和⽤于 Spring Boot 应⽤程序的 OpenAPI 3 ⽣成⼯具。
例⼦
作为本⽂中的代码⽰例，我们将使⽤使⽤ Spring Cloud 构建的典型微服务架构。它由 Spring Cloud Config Server、Eureka 发现和作为 API ⽹关的 Spring Cloud Gateway 组成。我们还有三个微服务，外部客户端只能通过⽹关才能访问它们暴露 REST API 。下图显⽰了本⽂所提
及的系统简单架构图。
执⾏
与 Springdoc OpenAPI 库相关的第⼀个好消息是它可以与 SpringFox 库⼀起存在⽽不会发⽣任何冲突。如果有⼈使⽤您的 Swagger ⽂
档，要为基于标准 Spring MVC 的应⽤程序启⽤ Springdoc，您需要将以下依赖项包含到 Maven 中l。
1 2 3 4 5<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webmvc-core</artifactId> <version>1.2.32</version>
</dependency>
我们的每个 Spring Boot 微服务都构建在 Spring MVC 之上，并为标准同步 REST 通信提供端点。但是，构建在 Spring Cloud Gateway 之上的 API ⽹关使⽤ Netty 作为嵌⼊式服务器，并基于响应式 Sprin
g WebFlux。它还提供 Swagger UI 以访问所有微服务公开的⽂档，因此它必须包含启⽤ UI 的库。必须包含以下两个库才能为基于 Spring WebFlux 的响应式应⽤程序启⽤ Springdoc ⽀持。
1
2 3 4 5 6 7 8 9 10<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webflux-core</artifactId> <version>1.2.31</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webflux-ui</artifactId> <version>1.2.31</version>
</dependency>
我们可以通过在 Spring Boot 配置⽂件中设置属性或使⽤@Beans. 例如，我们不想为应⽤程序公开的所有 HTTP 端点（如 Spring 特定端点）⽣成 OpenAPI 清单，因此我们可以定义⼀个基本包属性⽤于扫描，如下所⽰。在我们的源代码⽰例中，每个应⽤程序 YAML 配置⽂件都位于config-service模块中。
1 2springdoc:
packagesToScan: pl.piomin.services.department
这是员⼯服务的主要类。我们使⽤@OpenAPIDefinition注释来定义 Swagger 站点上显⽰的应⽤程序的描述。如您所见，我们仍然可以使⽤@EnableSwagger2.
1 2 3 4 5 6 7 8 9 10 11 12 13@SpringBootApplication
@EnableDiscoveryClient
@EnableSwagger2
@OpenAPIDefinition(info =
@Info(title = "Employee API", version = "1.0", description = "Documentation Employee API v1.0") )
public class EmployeeApplication {
public static void main(String[] args) {
springcloud集成log4j2SpringApplication.run(EmployeeApplication.class, args);
}
}
⼀旦您启动每个微服务，它将公开端点/v3/api-docs。我们可以通过使⽤springdoc.api-docs.path Spring 配置⽂件中的属性来⾃定义该上下⽂。由于不是必须的，我们可以继续在 Spring Cloud Gateway 上实现。Springdoc 没有提供与 SpringFox 类似的类SwaggerResource，它在上⼀篇⽂章中⽤于暴露来⾃不同微服务的多个 API。幸运的是，有⼀种分组机制允许将 OpenAPI 定义分成具有给定名称的不同组。要使⽤它，我们需要声明⼀个GroupOpenAPI bean列表。
这是⽹关服务中负责创建由⽹关处理的 OpenAPI 资源列表的代码⽚段。⾸先，我们使⽤RouteDefinitionLocator⾖。然后我们获取每个路由的 id 并将其设置为组名。因此，我们在 path 下有多个 OpenAPI 资源/v3/api-docs/{SERVICE_NAME}，例如/v3/api-docs/employee。
1 2 3 4 5 6 7 8 9 10 11 12 13@Autowired
RouteDefinitionLocator locator;
@Bean
public List<GroupedOpenApi> apis() {
List<GroupedOpenApi> groups = new ArrayList<>();
List<RouteDefinition> definitions = RouteDefinitions().collectList().block();
definitions.stream().filter(routeDefinition -> Id().matches(".*-service")).forEach(routeDefinition -> { String name = Id().replaceAll("-service", "");
GroupedOpenApi.builder().pathsToMatch("/"+ name + "/**").setGroup(name).build();
});
return groups;
}
1 2
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25spring:
cloud:
gateway:
discovery:
locator:
enabled: true
routes:
- id: employee-service
uri: lb://employee-service
predicates:
-
Path=/employee/**
filters:
- RewritePath=/employee/(?<path>.*), /$\{path} - id: department-service
uri: lb://department-service
predicates:
- Path=/department/**
filters:
- RewritePath=/department/(?<path>.*), /$\{path} - id: organization-service
uri: lb://organization-service
predicates:
- Path=/organization/**
filters:
- RewritePath=/organization/(?<path>.*), /$\{path}
由于 Springdoc 不允许⾃定义分组机制的默认⾏为来更改⽣成的路径，因此我们需要提供⼀些解决⽅法。我的提议只是在专⽤于 Open API 路径处理的⽹关配置中添加⼀个新的路由定义。它将路径重写/v3/api-docs/{SERVICE_NAME}为/{SERVICE_NAME}/v3/api-docs，由另⼀个负责与Eureka 发现交互的路由处理。
1
- id: openapi
23456
uri: localhost:${server.port}
predicates:
- Path=/v3/api-docs/** filters: - RewritePath=/v3/api-docs/(?<path>.*), /$\{path}/v3/api-docs
测试
访问在⽹关上公开的 Swagger UI
后，您可能会看到我们可以在发现中注册的所有三个微服务之间进⾏选择。这正是我们想要实现的。
结论
Springdoc OpenAPI 兼容 OpenAPI 3，并⽀持 Spring WebFlux ，⽽ SpringFox 不⽀持。因此，选择似乎是显⽽易见的，特别是如果您使⽤的是响应式 API 或 Spring Cloud Gateway 。在本⽂中，我向您展⽰了如何在具有⽹关模式的微服务架构中使⽤ Springdoc 。
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论