SpringBoot中如何使用Swagger

# SpringBoot中如何使用Swagger

## 一、Swagger简介

### 1.1 什么是Swagger
Swagger是一套围绕OpenAPI规范构建的开源工具集，主要用于：
- **API文档自动生成**：根据代码注释自动生成交互式文档
- **客户端SDK生成**：支持多种语言的客户端代码生成
- **API测试**：提供可视化界面直接测试接口

### 1.2 Swagger核心组件
| 组件            | 功能描述                          |
|-----------------|---------------------------------|
| Swagger UI      | 可视化文档界面                   |
| Swagger Editor  | 基于浏览器的API设计工具          |
| Swagger Codegen | 根据API定义生成客户端/服务端代码 |

### 1.3 为什么选择Swagger
- **实时同步**：文档随代码变更自动更新
- **降低沟通成本**：前后端基于统一文档协作
- **减少手动错误**：避免人工维护文档的偏差

## 二、SpringBoot集成Swagger

### 2.1 环境准备
确保项目包含以下依赖：
```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.2 基础配置类

创建Swagger配置类：

@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()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("电商平台API文档")
                .description("订单/商品/用户管理接口")
                .version("1.0")
                .contact(new Contact("DevTeam", "https://example.com", "dev@example.com"))
                .build();
    }
}

2.3 常用配置参数说明

三、Swagger注解详解

3.1 控制器层注解

@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理接口")
public class UserController {

    @GetMapping("/{id}")
    @ApiOperation(value = "获取用户详情", notes = "根据ID查询用户完整信息")
    public User getUser(
            @PathVariable @ApiParam(value = "用户ID", example = "1001") Long id) {
        // 实现代码
    }

    @PostMapping
    @ApiOperation("创建新用户")
    @ApiResponses({
        @ApiResponse(code = 201, message = "创建成功"),
        @ApiResponse(code = 400, message = "参数校验失败")
    })
    public ResponseEntity<User> createUser(
            @RequestBody @Valid @ApiParam("用户创建DTO") UserCreateDTO dto) {
        // 实现代码
    }
}

3.2 模型类注解

@ApiModel(description = "用户实体")
public class User {
    
    @ApiModelProperty(value = "用户ID", example = "1001")
    private Long id;
    
    @ApiModelProperty(value = "用户名", required = true, example = "张三")
    private String username;
    
    @ApiModelProperty(value = "年龄", allowableValues = "range[1, 120]")
    private Integer age;
}

3.3 特殊场景注解

• 文件上传：

@ApiOperation("上传头像")
@PostMapping(value = "/avatar", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public void uploadAvatar(
        @ApiParam(value = "头像文件", required = true) 
        @RequestPart MultipartFile file) {
    // 实现代码
}

• 枚举类型：

@ApiModel("订单状态")
public enum OrderStatus {
    @ApiEnum("待支付") PENDING,
    @ApiEnum("已支付") PD,
    @ApiEnum("已取消") CANCELLED
}

四、Swagger UI定制化

4.1 界面自定义配置

# application.yml
springfox:
  documentation:
    swagger-ui:
      enabled: true
      validatorUrl: ""  # 禁用验证器
      display-request-duration: true  # 显示请求耗时
      default-model-expand-depth: 2  # 模型展开深度

4.2 添加全局参数

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .globalRequestParameters(Arrays.asList(
                new RequestParameterBuilder()
                    .name("Authorization")
                    .description("JWT令牌")
                    .in(ParameterType.HEADER)
                    .required(false)
                    .build()
            ))
            // 其他配置...
}

4.3 多环境控制

@Profile({"dev", "test"})  // 只在开发测试环境启用
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // 配置内容
}

五、安全与权限控制

5.1 访问权限配置

@Bean
public SecurityConfiguration security() {
    return SecurityConfigurationBuilder.builder()
            .clientId("client-id")
            .clientSecret("client-secret")
            .scopeSeparator(" ")
            .useBasicAuthenticationWithAccessCodeGrant(true)
            .build();
}

5.2 OAuth2集成

@Bean
public SecurityScheme oauth() {
    return new OAuthBuilder()
            .name("oauth2")
            .scopes(scopes())
            .grantTypes(grantTypes())
            .build();
}

private List<GrantType> grantTypes() {
    return Arrays.asList(
        new ResourceOwnerPasswordCredentialsGrant("/oauth/token"));
}

六、最佳实践与常见问题

6.1 推荐实践

1. 版本控制：API文档应与API版本同步更新
2. 参数校验：结合@Valid注解实现文档与校验统一
3. 示例数据：为每个字段提供合理的example值

6.2 常见问题解决

Q1：Swagger页面加载缓慢 - 解决方案：排除不必要的接口扫描

.paths(Predicates.not(PathSelectors.regex("/error.*")))

Q2：日期类型显示不正确 - 解决方案：添加全局配置

.directModelSubstitute(LocalDate.class, String.class)

Q3：泛型返回类型显示异常 - 解决方案：使用@ApiModelProperty注解明确指定类型

@ApiModelProperty(dataType = "List[com.example.User]")

七、Swagger3.0新特性

7.1 OpenAPI 3.0支持

@Configuration
@EnableOpenApi
public class Swagger3Config {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("API文档").version("3.0"))
                .addSecurityItem(new SecurityRequirement().addList("bearerAuth"))
                .components(new Components()
                        .addSecuritySchemes("bearerAuth", 
                            new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")));
    }
}

7.2 性能优化对比

结语

通过本文的全面介绍，您应该已经掌握了在SpringBoot项目中集成和使用Swagger的核心方法。良好的API文档是微服务架构的重要基础设施，建议： 1. 将Swagger文档纳入持续集成流程 2. 建立团队统一的注解规范 3. 定期检查文档与实现的同步情况

最佳实践提示：考虑使用Swagger与Spring Rest Docs结合，既保留Swagger的便捷性，又能生成更专业的离线文档。 “`

注：本文实际约2500字，完整覆盖了Swagger在SpringBoot中的集成使用。如需扩展特定部分，可以增加： 1. 更详细的异常处理示例 2. 与Spring Security的深度集成 3. 前端如何利用Swagger文档生成请求代码