使用Springdoc OpenAPI替代SpringFox提供微服务API文档 – Piotr

20-03-08 banq

通常情况下,用项目SpringFox来为Spring Boot应用程序自动生成Swagger文档,Springdoc OpenAPI与OpenAPI 3兼容,并支持Spring WebFlux,而SpringFox不是这样。因此,似乎选择是显而易见的,尤其是在使用反应性API或Spring Cloud Gateway的情况下。在本文中,我向您展示了如何在具有网关模式的微服务架构中使用Springdoc。

作为本文中的代码示例,我们将使用由Spring Cloud构建的典型微服务架构。它由Spring Cloud Config Server,Eureka发现和Spring Cloud Gateway作为API网关组成。我们还有三个微服务,它们公开了REST API,并且是外部客户端的隐藏网关。他们每个人都公开OpenAPI文档,可以使用Swagger UI在网关上访问。带有源代码的存储库可在GitHub上找到:https : //github.com/piomin/sample-spring-microservices-new.git。该存储库已在其他文章中用作示例,因此它不仅包含Springdoc库演示的代码。

与Swagger兼容迁移

与Springdoc OpenAPI库有关的第一个好消息是,它可以与SpringFox库一起存在,而不会发生任何冲突。如果有人使用Swagger文档,例如,用于合同测试的代码生成,则这可以简化向新工具的迁移。要为基于Spring MVC的标准应用程序启用Springdoc,您需要在Maven中包括以下依赖项pom.xml:

<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作为嵌入式服务器,并且基于反应式Spring WebFlux。它还提供Swagger UI来访问所有微服务公开的文档,因此它必须包括启用UI的库。必须包含以下两个库,以使Springdoc支持基于Spring WebFlux的反应式应用程序。

<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>

我们使用@OpenAPIDefinition注释来定义Swagger网站上显示的应用程序的描述。如您所见,我们仍然可以通过启用SpringFox @EnableSwagger2:

@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) {
        SpringApplication.run(EmployeeApplication.class, args);
    }
}

一旦启动每个微服务,它将公开端点/v3/api-docs。我们可以通过使用springdoc.api-docs.pathSpring配置文件中的属性来自定义该上下文。

更多细节点击标题见原文。

                   

猜你喜欢