如何在 Spring Boot 3 上运行 Swagger 3

Question

使用带有 Java17 和 Spring Boot 3.0.0 的全新 Spring Initialzr，以及对 Springfox Swagger 3 的 pom.xml 的额外添加，我终生无法让 Swagger 页面正常工作。相反，我得到了带有 404 的 whitelabel 错误页面。

Pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.0.0</version>
    <relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.example</groupId>
<artifactId>demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>demo</name>
<description>Demo project for Spring Boot</description>
<properties>
    <java.version>17</java.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>
</project>

此 Github 问题页面中定义的标准 Swagger URL 不适用于上述 pom.xml 项目。

Answer 1

发题后就放弃了，转而使用Spring Boot 2.7。但是，在看到 Dmitriy 的回答之后，我最后一次检查了 Springdoc，发现Springdoc v2 确实支持 Spring Boot 3.

本质上，必须在他们的 pom 中放置以下内容：

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.0.0</version>
   </dependency>

然后可以使用以下 URL 访问 Swagger 页面：http://localhost:8080/swagger-ui.html（如果需要，请不要忘记添加上下文路径）。出于某种原因，在打开时，它重定向到 http://localhost:8080/swagger-ui/index.html 尽管最初返回 404...

Answer 2

除了按照接受的答案中的指示添加

springdoc-openapi-starter-webmvc-ui

（对我来说是v2.0.2）之外，我还需要删除

org.springdoc:springdoc-openapi-ui:1.6.13

.

它在那里，因为我以前尝试过。如果存在，仍然有一个非 Jakarta 引用，Spring 试图解析（但未能解析）。

我还需要添加这个依赖项，否则我会在启动时收到一条讨厌的消息（版本由 Spring Boot BOM 解析）：

implementation group: 'org.hibernate.validator', name: 'hibernate-validator'

Answer 3

Springdoc 使用 Spring boot 3.0.1

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.0.2</version>
   </dependency>

默认网址：http://localhost:8080/swagger-ui/index.html

Answer 4

我同意@Ahmed Tawfik，因为我也面临同样的问题。但是今天我用新版本的“springdoc-openapi-starter-webmvc-ui”依赖项和 Spring Boot 3.0.2-SNAPSHOT 尝试了同样的方法。

    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.0.2</version>
    </dependency>

因为之前的“springdoc-openapi-ui”改成了上面的

此外，在 swagger UI 的安全配置路径下方包含

"/v3/api-docs/**","/swagger-ui/**"

对于我的项目，

@Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        return http.cors(AbstractHttpConfigurer::disable)
                .csrf(AbstractHttpConfigurer::disable)
                .exceptionHandling(exceptionHandlingConfigurer -> exceptionHandlingConfigurer.authenticationEntryPoint(unauthorizedHandler))
                .authorizeHttpRequests(authorizationManagerRequestMatcherRegistry -> {
                            try {
                                authorizationManagerRequestMatcherRegistry
                                        .requestMatchers(HttpMethod.POST, POST_AUTH_WHITELIST).permitAll()
                                        .requestMatchers(HttpMethod.GET, GET_AUTH_WHITELIST).permitAll()
                                        .requestMatchers("/v3/api-docs/**", "/swagger-ui/**").permitAll()
                                        .anyRequest()
                                        .authenticated()
                                        .and()
                                        .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS));
                            } catch (Exception e) {
                                throw new ResourceNotFoundException(e.getMessage());
                            }
                        }
                )
                .formLogin(AbstractHttpConfigurer::disable)
                .httpBasic(AbstractHttpConfigurer::disable).addFilterBefore(jwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class)
                .authenticationProvider(daoAuthenticationProvider()).build();
    }

招摇的 UI 链接将是：

http://server:port/context-path/swagger-ui.html

请根据您的个人更改调整server、port和context-path。

上述所有步骤都适用于我的项目。我不需要额外的配置。

此外，您可以添加自定义路径（可选）：

springdoc.swagger-ui.path=/swagger-ui.html

这里是 OpenApi 3 和 Spring Boot 的官方文档：https://springdoc.org/v2/#features

在上面的文档中，您还可以探索其他配置和其他内容。

快乐学习！ ✌️

Answer 5

对于 Gradle，您可以添加：

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.0'

Answer 6

最新 springfox-boot-starter 版本 3.0.0 和 springdoc-openapi-ui 1.6.13

好像不支持spring-boot 3.

需要等新版本采用jakarta.servlet包

Answer 7

对于 Spring Boot 3，使用 springdoc-openapi v2

以下是在 Spring Boot 3 上运行并支持基于 JWT 的身份验证的示例步骤：

在pom.xml文件中添加如下依赖：

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
   <version>2.0.4</version>
</dependency>

创建一个名为

OpenApiConfig

的新类。在此示例中使用了基于注释的配置，但也可以通过编程方式进行配置。

@Configuration
@OpenAPIDefinition(info = @Info(title = "REST API", version = "1.0",
        description = "REST API description...",
        contact = @Contact(name = "Name Surname")),
        security = {@SecurityRequirement(name = "bearerToken")}
)
@SecuritySchemes({
        @SecurityScheme(name = "bearerToken", type = SecuritySchemeType.HTTP, 
                        scheme = "bearer", bearerFormat = "JWT")
})

然后通过添加访问权限所需的 url 来更新您的 SecurityConfig 类：

private static final String[] AUTH_WHITELIST = {
        "/api/v1/auth/**",
        "/v3/api-docs/**",
        "/v3/api-docs.yaml",
        "/swagger-ui/**",
        "/swagger-ui.html"
};

@Bean
public SecurityFilterChain filterChain(HttpSecurity httpSecurity) throws Exception{
    httpSecurity
            // ...
            .authorizeHttpRequests()
            .requestMatchers(AUTH_WHITELIST).permitAll()
            .anyRequest().authenticated();
    // ...
}

运行应用程序并访问 http://localhost:8080/swagger-ui/index.html 上的文档

Answer 8

以下依赖项对我来说工作正常。

<project xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.sample.app</groupId>
    <artifactId>hello-world</artifactId>
    <version>1.0.0</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.0.1</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>


        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.0.0</version>
        </dependency>

    </dependencies>
</project>

Answer 9

最新版本的springdoc-openapi 兼容Springboot 3 (jakarta) 改动。使用最新版本为我解决了这个问题。

https://springdoc.org/v2/

Answer 10

似乎 springfox 版本的 swagger 不适用于 spring 3.0。一个替代方案是 openAPI。添加以下依赖项以使其工作

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

Answer 11

使用 Open API 而不是 Spring v3.0 的 swagger。按照这个文档Open API Docs

Answer 12

对于 Spring boot 3 及更高版本，我们在这里添加了这个依赖项

   <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-common</artifactId>
        <version>2.1.0</version>
    </dependency>

对于包含 spring security 的项目，我们需要允许以下路径以忽略@AuthenticationPrincipal 参数。

    private static final String[] AUTH_WHITELIST = {
        "/api/v1/auth/**",
        "/v3/api-docs/**",
        "/v3/api-docs.yaml",
        "/swagger-ui/**",
        "/swagger-ui.html"
};

更多资源👉看这个或阅读这个文件

如何在 Spring Boot 3 上运行 Swagger 3

问题描述投票：0回答：12

12个回答

最新问题

如何在 Spring Boot 3 上运行 Swagger 3

问题描述 投票：0回答：12

12个回答

最新问题

问题描述投票：0回答：12