SpringBoot如何整合OpenApi

# SpringBoot如何整合OpenApi

## 目錄
1. [OpenAPI與Swagger簡介](#1-openapi與swagger簡介)
2. [SpringBoot集成OpenAPI的三種方式](#2-springboot集成openapi的三種方式)
3. [基于SpringDoc的完整整合方案](#3-基于springdoc的完整整合方案)
4. [OpenAPI規范的高級配置](#4-openapi規范的高級配置)
5. [接口安全與權限控制](#5-接口安全與權限控制)
6. [生產環境最佳實踐](#6-生產環境最佳實踐)
7. [常見問題解決方案](#7-常見問題解決方案)

---

## 1. OpenAPI與Swagger簡介

### 1.1 什么是OpenAPI規范
OpenAPI規范（前身Swagger規范）是RESTful API設計的行業標準，通過YAML或JSON格式描述API的：
- 端點（Endpoints）
- 操作（HTTP方法）
- 參數（查詢/路徑/請求體）
- 返回格式
- 認證方式

```yaml
# 示例：OpenAPI 3.0定義
openapi: 3.0.3
info:
  title: 用戶服務API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 獲取用戶列表
      responses:
        '200':
          description: 成功返回用戶數組

1.2 Swagger工具生態

• Swagger UI：交互式API文檔界面
• Swagger Editor：基于瀏覽器的規范編輯器
• Swagger Codegen：根據規范生成客戶端SDK

1.3 SpringBoot支持現狀

自SpringFox 3.0停止維護后，主流方案遷移至： - SpringDoc OpenAPI（推薦） - Swagger Core原生集成

2. SpringBoot集成OpenAPI的三種方式

2.1 方案對比

2.2 基礎依賴配置

<!-- pom.xml示例 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

2.3 自動生成原理

SpringDoc通過掃描以下Spring注解自動構建OpenAPI模型： - @RestController - @RequestMapping - @Operation（Swagger注解） - @Parameter

3. 基于SpringDoc的完整整合方案

3.1 基礎配置類

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "電商平臺API",
        version = "v1.0",
        contact = @Contact(name = "Dev Team", email = "dev@example.com")
    )
)
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .components(new Components()
                .addSecuritySchemes("bearerAuth", 
                    new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT")))
            .addSecurityItem(
                new SecurityRequirement().addList("bearerAuth"));
    }
}

3.2 控制器注解示例

@RestController
@RequestMapping("/api/products")
@Tag(name = "商品管理", description = "商品CRUD操作")
public class ProductController {

    @Operation(summary = "獲取商品詳情", 
               parameters = @Parameter(name = "id", description = "商品ID"))
    @ApiResponse(responseCode = "404", description = "商品不存在")
    @GetMapping("/{id}")
    public Product getProduct(@PathVariable Long id) {
        // 實現邏輯
    }
}

3.3 實體類文檔化

@Schema(description = "商品數據模型")
public class Product {
    
    @Schema(description = "商品唯一ID", example = "1001")
    private Long id;
    
    @Schema(description = "商品名稱", requiredMode = REQUIRED)
    private String name;
}

4. OpenAPI規范的高級配置

4.1 分組API文檔

@Bean
@GroupedOpenApi
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
        .group("admin")
        .pathsToMatch("/admin/**")
        .build();
}

4.2 自定義響應示例

@Operation(responses = {
    @ApiResponse(
        responseCode = "200",
        content = @Content(
            mediaType = "application/json",
            examples = @ExampleObject(
                value = "{\"code\":200,\"data\":{\"name\":\"示例商品\"}}"
            )
        )
    )
})

4.3 多環境配置策略

# application-prod.yml
springdoc:
  swagger-ui:
    enabled: false
  api-docs:
    enabled: false

5. 接口安全與權限控制

5.1 JWT認證集成

.securitySchemes(List.of(
    new SecurityScheme()
        .name("Authorization")
        .type(HTTP)
        .scheme("bearer")
        .bearerFormat("JWT")
))

5.2 角色權限過濾

@Hidden  // 隱藏接口
@PreAuthorize("hasRole('ADMIN')")
public void deleteProduct() {}

6. 生產環境最佳實踐

6.1 性能優化建議

• 啟用緩存：springdoc.cache.disabled=false
• 限制掃描路徑：springdoc.packagesToScan=com.example.api

6.2 安全防護措施

@Bean
public OpenApiCustomiser addSecurityHeaders() {
    return openApi -> openApi.getPaths().values()
        .forEach(pathItem -> pathItem.readOperations()
            .forEach(operation -> 
                operation.addParametersItem(new HeaderParameter()
                    .required(false)
                    .name("X-Request-ID"))));
}

7. 常見問題解決方案

7.1 跨域問題處理

springdoc:
  cors:
    enabled: true
    paths: /**

7.2 枚舉類型顯示優化

@Schema(type = "string", allowableValues = {"A","B","C"})
private StatusEnum status;

7.3 文件上傳文檔化

@Operation(requestBody = @RequestBody(
    content = @Content(mediaType = "multipart/form-data",
        schema = @Schema(type = "object"),
        encoding = @Encoding(name = "file", contentType = "application/octet-stream"))
)

最佳實踐總結：建議采用SpringDoc作為主要集成方案，配合注解驅動開發，同時通過@Profile控制生產環境文檔暴露。完整示例代碼可參考GitHub示例倉庫 “`

（注：此為精簡版框架，完整5100字版本需擴展每個章節的詳細實現步驟、原理圖解、性能對比數據等內容）