SpringBoot3使用Swagger3

在Spring Boot 3中使用Swagger 3

Swagger 是一个强大的API文档生成工具，它可以帮助开发者快速创建、更新和管理API文档。随着Spring Boot 3的发布，Swagger也更新到了3.x版本，提供了更好的特性和功能。本文将介绍如何在Spring Boot 3中集成Swagger 3，并提供一些基本的代码示例。

1. 项目依赖

首先，我们需要在Spring Boot项目中添加Swagger的依赖。可以在pom.xml文件中添加以下依赖：

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

2. 配置Swagger

接下来，我们需要在项目中进行Swagger的基本配置。这通常是在一个配置类中完成的。我们可以创建一个名为SwaggerConfig的配置类，代码如下：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller")) // 指定扫描的包
                .paths(PathSelectors.any())
                .build();
    }
}

在上述代码中，我们创建了一个Docket实例，指定了API文档的类型为Swagger 2，并设置了API的扫描基础包。

3. 编写示例Controller

接下来，我们将创建一个示例Controller，并为其添加Swagger注解。如下所示：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api")
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

4. 访问Swagger UI

完成上述步骤后，启动Spring Boot应用。Swagger UI通常在http://localhost:8080/swagger-ui/下访问（端口号根据实际配置而定）。在这个页面中，可以看到我们定义的API文档，并能够进行API的调用测试。

5. 自定义API文档信息

在SwaggerConfig类中，我们还可以自定义一些API文档的信息，例如标题、描述等。更新配置如下：

import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;

import static springfox.documentation.builders.PathSelectors.regex;

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
            .paths(regex("/api.*")) // 只扫描/api开头的路径
            .build()
            .apiInfo(apiInfo());
}

private ApiInfo apiInfo() {
    return new ApiInfo(
            "示例API文档",
            "这是使用Swagger生成的API文档示例。",
            "1.0",
            "Terms of service",
            new Contact("张三", "www.example.com", "example@example.com"),
            "License of API",
            "API license URL",
            Collections.emptyList()
    );
}

6. 结论

在Spring Boot 3中集成Swagger 3非常简单，可以通过这些步骤快速生成API文档。使用Swagger可以显著提升开发效率，也便于团队协作，让每位成员能够更清晰地了解API的使用方式。希望这篇文章能够帮助你在项目中顺利使用Swagger！