【SpringBoot实战】揭秘！如何轻松整合Swagger3，打造高效在线Api文档

在Spring Boot项目中整合Swagger3，可以方便地生成和查看API文档。以下是详细的步骤和代码示例：

1. 添加依赖

首先，在你的pom.xml文件中添加Swagger相关的依赖：

<dependencies>
    <!-- Spring Boot Starter Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Swagger3 Dependencies -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
</dependencies>

2. 配置Swagger

创建一个配置类来配置Swagger：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo")) // 修改为你的包名
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot API")
                .description("Spring Boot REST API documentation")
                .version("1.0.0")
                .build();
    }
}

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 sayHello() {
        return "Hello, World!";
    }
}

4. 启动应用并访问Swagger UI

启动你的Spring Boot应用程序，然后在浏览器中访问以下URL：

http://localhost:8080/swagger-ui/index.html

你应该能够看到Swagger UI界面，并且可以看到你定义的API端点。

5. 自定义Swagger配置（可选）

你可以进一步自定义Swagger的配置，例如添加更多的信息、设置扫描路径等。以下是一个更复杂的配置示例：

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

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo")) // 修改为你的包名
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot API")
                .description("Spring Boot REST API documentation")
                .version("1.0.0")
                .contact(new Contact("Your Name", "yourwebsite.com", "youremail@example.com"))
                .build();
    }
}

通过以上步骤，你已经成功地在Spring Boot项目中整合了Swagger3，并生成了在线API文档。这样，你可以更方便地进行API的开发和维护。