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文檔生成請求代碼