轻松搞定！SpringBoot3集成Swagger的正确姿势

2023-02-06 18:09:59

SpringBoot 3 中整合 Swagger 的常见错误及解决方案

简介

将 Swagger 集成到 SpringBoot 3 中可以让你轻松地生成 API 文档，从而方便地测试和调试应用程序。但是，在集成过程中，可能会遇到一些错误。本文将深入探讨 SpringBoot 3 集成 Swagger 时最常见的错误之一，并提供详细的解决方案。

错误：创建 bean 失败，名称为 "apiDocumentationScanner"，定义在 URL 中

症状

在 SpringBoot 3 中集成 Swagger 时，你可能会遇到以下错误消息：

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'apiDocumentationScanner' defined in URL [file:.../spring-boot-autoconfigure-processor-3.0.0.M5.jar!/org/springframework/boot/autoconfigure/http/ApiDocumentationConfiguration.class]: Invocation of init method failed; nested exception is java.lang.NoSuchMethodError: 'org.springframework.context.annotation.AnnotationConfigApplicationContext org.springframework.context.annotation.AnnotationConfigApplicationContext(java.lang.Class\[], org.springframework.context.annotation.AnnotatedBeanDefinitionReader, java.lang.String...)'

原因

此错误是由 SpringBoot 3 中的 API 文档功能的变化引起的。SpringBoot 3 引入了 SpringDoc2 作为默认的 API 文档工具，取代了早期的 Swagger 版本。

解决方案

要解决此错误，你需要执行以下步骤：

从 POM 中删除旧的 Swagger 依赖项。
添加 SpringDoc2 依赖项。 在你的 pom.xml 文件中添加以下依赖项：

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

在 application.properties 中添加 SpringDoc2 配置。 添加以下配置：

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

使用 @ApiOperation 和 @ApiResponses 注解生成 Swagger 文档。 在你的 Controller 中使用这些注解来 API 的操作和响应。

代码示例

以下是一个使用 SpringDoc2 生成 Swagger 文档的简单示例：

import org.springframework.web.bind.annotation.*;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@RestController
public class ExampleController {

    @Operation(summary = "Get a user by ID")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "OK"),
            @ApiResponse(responseCode = "404", description = "User not found")
    })
    @GetMapping("/users/{id}")
    public User getUserById(@PathVariable Long id) {
        return new User();
    }
}