SpringBoot配置Swagger3详解-快速集成与使用指南

在Spring Boot项目中配置Swagger 3（OpenAPI 3）可以帮助生成RESTful API的文档，方便开发者测试和调试。以下是配置Swagger 3的详细步骤：

1. 添加依赖

在pom.xml中添加Swagger 3（springdoc-openapi）的依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version> <!-- 使用版本 -->
</dependency>

说明：springdoc-openapi 是目前支持Swagger 3（OpenAPI 3）的主流库，与Spring Boot无缝集成。

2. 配置基本设置（可选）

在application.yml或application.properties中，可以配置Swagger的基本信息，例如API标题、描述、版本等。

示例（`application.yml`）：

springdoc:
  api-docs:
    path: /api-docs # 自定义API文档路径（默认是/v3/api-docs）
  swagger-ui:
    path: /swagger-ui.html # 自定义Swagger UI路径（默认是/swagger-ui.html）
  info:
    title: 示例API文档
    description: 这是一个使用Spring Boot和Swagger 3生成的API文档
    version: 1.0.0

3. 启用Swagger功能

springdoc-openapi会自动扫描Spring Boot项目中的Controller并生成文档，因此通常不需要额外的配置类。但你可以通过以下方式进一步自定义。

示例：

如果需要添加全局的元数据配置，可以创建一个配置类：

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

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("示例API文档")
                        .version("1.0.0")
                        .description("这是一个使用Spring Boot和Swagger 3生成的API文档"));
    }
}

4. 标注API接口

在Controller中，通过注解描述API接口的信息，例如接口说明、参数描述、返回值等。

示例：

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 org.springframework.web.bind.annotation.*;

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

    @GetMapping("/{id}")
    @Operation(summary = "根据ID获取用户信息", 
               description = "通过用户ID获取用户的详细信息",
               responses = {
                   @ApiResponse(responseCode = "200", description = "成功", 
                               content = @Content(mediaType = "application/json", 
                                                  schema = @Schema(implementation = User.class))),
                   @ApiResponse(responseCode = "404", description = "用户未找到")
               })
    public User getUserById(
            @Parameter(description = "用户ID", required = true) 
            @PathVariable Long id) {
        // 模拟返回用户信息
        return new User(id, "张三", "zhangsan@example.com");
    }
}

// 示例实体类
class User {
    private Long id;
    private String name;
    private String email;

    // 构造器、Getter和Setter省略
}

5. 访问Swagger UI

启动Spring Boot项目后，可以通过以下URL访问Swagger UI：
- 默认路径：http://localhost:8080/swagger-ui.html
- 如果自定义了路径，例如/docs，则访问：http://localhost:8080/docs

在Swagger UI中，你可以查看所有标注的API接口，并直接进行在线测试。

6. 常见问题

问题1：Swagger UI无法加载？

确保依赖已正确添加。
检查Spring Boot版本是否与springdoc-openapi兼容。
确保项目已启动，并且访问路径正确。

问题2：如何隐藏某些接口？

使用@Hidden注解隐藏接口：

import io.swagger.v3.oas.annotations.Hidden;

@GetMapping("/hidden")
@Hidden
public String hiddenEndpoint() {
    return "这个接口不会出现在Swagger文档中";
}

问题3：如何分组管理API？

使用@Tag注解为Controller或接口分组：

import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api/orders")
@Tag(name = "订单管理", description = "订单相关的API接口")
public class OrderController {
    // 接口代码
}