java - 如何使用 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

你可以这样做@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 3

即使您的应用程序使用没有（spring-boot）的spring，它也应该可以工作。您需要添加 spring-boot 中本机提供的 bean 和依赖项自动配置。

您主要需要添加springdoc-openapi模块并扫描自动为您加载的 springdoc 自动配置类spring-boot。根据您的模块，您可以在spring.factories每个springdoc-openapi模块的文件中找到它们：

例如，假设您要加载swagger-uiinspring-mvc应用程序，并且您正在使用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 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>