如何在 Spring Boot 项目中实现对 Swagger 的集成？

在 Spring Boot 项目中集成 Swagger 可以方便地生成 API 文档，便于前后端开发人员进行对接。下面以 Swagger 3（OpenAPI 3）为例，介绍在 Spring Boot 项目中集成 Swagger 的具体步骤。

1. 添加依赖

在 pom.xml（如果是 Maven 项目）中添加如下依赖：

<dependencies>
    <!-- Springdoc OpenAPI 3 -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.2.0</version>
    </dependency>
</dependencies>

这个依赖会自动集成 Swagger UI 界面，同时支持 OpenAPI 3 规范。

2. 配置 Swagger

通常情况下，无需额外配置，Springdoc 会自动扫描项目中的控制器并生成 API 文档。不过，你也可以通过配置类进行一些自定义设置，例如：

SwaggerConfig.java

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
               .info(new Info()
                       .title("Your API Title")
                       .description("Your API Description")
                       .version("1.0.0"));
    }
}    

3. 使用注解描述 API

在控制器类和方法上使用 Swagger 注解来描述 API 的信息，例如：

UserController.java

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

@RestController
@RequestMapping("/users")
public class UserController {

    @Operation(summary = "Get a user by ID")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Found the user",
                    content = {@Content(mediaType = "application/json",
                            schema = @Schema(implementation = User.class))}),
            @ApiResponse(responseCode = "404", description = "User not found",
                    content = @Content)})
    @GetMapping("/{id}")
    public User getUserById(@Parameter(description = "ID of user to be searched") @PathVariable Long id) {
        // 这里实现获取用户的逻辑
        return new User();
    }

    // 定义 User 类
    static class User {
        private Long id;
        private String name;

        // Getters and Setters
        public Long getId() {
            return id;
        }

        public void setId(Long id) {
            this.id = id;
        }

        public String getName() {
            return name;
        }

        public void setName(String name) {
            this.name = name;
        }
    }
}    

4. 访问 Swagger UI

启动 Spring Boot 项目后，在浏览器中访问以下 URL 即可查看 Swagger UI 界面：

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

总结

• 添加 Springdoc OpenAPI 3 的依赖。
• 可以通过配置类进行自定义设置。
• 使用 Swagger 注解描述 API 的信息。
• 访问 http://localhost:8080/swagger-ui.html 查看 API 文档。

通过以上步骤，你就可以在 Spring Boot 项目中成功集成 Swagger 并生成美观易用的 API 文档。