如何使用 springdoc-openapi 將 Open API 3 與 Spring 項目（不是 Spring Boot）集成

Question

我現有的項目是在 Spring Framework 而不是 Spring Boot.

我想將 Open API 3 與它集成。

我想使用 springdoc-openapi 進行集成，而不是使用 Jersey。

Answer 1

使用 springdoc-openapi-ui 1.5.2 的 spring-mvc (5.3.1) ui 加載看起來更簡單：

build.gradle（gradle 版本 6.5）

implementation 'org.springdoc:springdoc-openapi-ui:1.5.2'

在依賴項部分中不需要明確的 spring-boot-autoconfigure 和 spring-boot，因為 org.springdoc:springdoc-openapi-ui:1.5.2 已經擁有它們（版本 2.4.0）。 您會驚訝於最終應用程序中將添加多少和哪些依賴項。

OpenApiConfig.java

@Configuration
@EnableWebMvc
@ComponentScan(basePackages = {"org.springdoc"})
@Import({org.springdoc.core.SpringDocConfiguration.class,
         org.springdoc.webmvc.core.SpringDocWebMvcConfiguration.class,
         org.springdoc.webmvc.ui.SwaggerConfig.class,
         org.springdoc.core.SwaggerUiConfigProperties.class,
         org.springdoc.core.SwaggerUiOAuthProperties.class,
         org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration.class})

class OpenApiConfig implements WebMvcConfigurer {
}

OpenApiConfig 包應該被組件掃描覆蓋。

在使用 Spring Security 的情況下，您可以添加兩個 url 模式並在代碼中定義 OpenAPI 頁面訪問的角色。

<security:intercept-url pattern="/swagger*/**" access="ROLE_DEVELOPER"/>
<security:intercept-url pattern="/v3/api-docs" access="ROLE_DEVELOPER"/>

要檢查的網址：

http://localhost:8080/your_context_path/swagger-ui.html
http://localhost:8080/your_context_path/v3/api-docs

Answer 2

即使您的應用程序在沒有 (spring-boot) 的情況下使用 spring，它也應該可以工作。 您需要添加 spring-boot 中原生提供的 bean 和依賴項自動配置。

您主要需要添加springdoc-openapi模塊並掃描spring-boot自動為您加載的 springdoc 自動配置類。 根據您的模塊，您可以在每個springdoc-openapi模塊的文件spring.factories中找到它們。

例如，假設您想在spring-mvc應用程序中加載swagger-ui ，並且您正在使用spring.version=5.1.12.RELEASE ，並且您

您可以添加以下依賴項：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.2.28</version>
</dependency>

如果您沒有spring-boot和spring-boot-autoconfigure依賴項，則需要添加它們。 並注意spring.verion和spring-boot.version之間的兼容性矩陣。 例如，在這種情況下（ spring.version=5.1.12.RELEASE ）：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot</artifactId>
    <version>2.1.11.RELEASE</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-autoconfigure</artifactId>
    <version>2.1.11.RELEASE</version>
</dependency>

在這種情況下，由於我們要為 spring-mvc 加載 ui，您需要在配置類之一中添加以下內容：

@Import({ org.springdoc.core.SpringDocConfiguration.class, 
          org.springdoc.core.SpringDocWebMvcConfiguration.class,
          org.springdoc.ui.SwaggerConfig.class, 
          org.springdoc.core.SwaggerUiConfigProperties.class,
          org.springdoc.core.SwaggerUiOAuthProperties.class,
          org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration.class
})

Answer 3

你可以用@Annotations做到這一點：

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.servers.Server;
import io.swagger.v3.oas.annotations.info.Info

@OpenAPIDefinition(info = @Info(title = "My REST API", version = "1.2.6",
            description = "My OpenAPIDefinition description"),
                servers = { @Server(url = "/my-api", description = "Default URL")})
public class OpenApiConfig { }

Springdoc OpenAPI UI對Maven Central Repository 的依賴：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.4.6</version>
</dependency>

Maven 中央存儲庫：

• https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui

Answer 4

這是一個使用 Spring 和嵌入式 Undertow Web 服務器構建的示例項目： https : //github.com/essentialprogramming/undertow-spring-web沒有 Spring Boot，即使它的行為像一個。 只需運行服務器。 主要類。 好了，Open API 將在http://localhost:8080/apidoc 下可用

您只需要使用所需的 bean 來裝飾 Spring WebApplicationContext：

private static  AnnotationConfigWebApplicationContext createSpringWebAppContext(String configLocation) {
    AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
    context.setConfigLocation(configLocation);
    context.register(
            org.springdoc.core.SwaggerUiConfigProperties.class, org.springdoc.core.SwaggerUiOAuthProperties.class,
            org.springdoc.core.SpringDocConfiguration.class, org.springdoc.core.SpringDocConfigProperties.class,
            org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration.class);
    return context;
}

Answer 5

在我加載 swagger-ui.html 頁面的案例中，我使用了 spring 5.3.3 版和 springdoc-openapi-ui 1.5.2 版。

我的班級配置是：

@Configuration
@EnableWebMvc
@ComponentScan(basePackages = "com.example")
@Import({org.springdoc.core.SpringDocConfiguration.class,
         org.springdoc.webmvc.core.SpringDocWebMvcConfiguration.class,
         org.springdoc.webmvc.ui.SwaggerConfig.class,
         org.springdoc.core.SwaggerUiConfigProperties.class,
         org.springdoc.core.SwaggerUiOAuthProperties.class,
         org.springdoc.core.SpringDocConfigProperties.class,
         org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration.class})
public class WebConfig implements WebMvcConfigurer{

}

和我的pom：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.2</version>
</dependency>

Answer 6

使用 OpenAPI 3.0 記錄 Spring REST API

要使用 OpenAPI 3.0 記錄您的 spring 啟動應用程序，請使用 baeldung 的這篇優秀文章。

https://www.baeldung.com/spring-rest-openapi-documentation

此外，您也可以更改 swagger 的 URI 路徑。

springdoc.swagger-ui.path=/swagger

上面的 /swagger 將我的上下文路徑指定為主機 swagger。

現在，我訪問 swagger 儀表板的 URI 路徑變為：

http://localhost:8080/swagger