使用Springdoc OpenAPI替代SpringFox提供微服務API文件 – Piotr

banq發表於2020-03-08
SpringAPI微服務

通常情況下，用專案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配置檔案中的屬性來自定義該上下文。
更多細節點選標題見原文。

相關文章