Swagger 全量注解應用指南：從@Tag到@SecurityScheme，全面掌握API設計

作者：肖哥談架構 2025-09-03 04:15:00

從基礎的@Tag、@Operation到高級的@SecurityScheme、@Callback，每個注解都配有清晰的代碼示例和實際應用案例。包含全局配置、多安全方案、復雜響應結構、Webhook回調等企業級場景，幫助你構建專業級的API文檔系統。

本文是Swagger注解的完整參考指南，詳細解析了6大類40+個核心注解的使用方法和實戰場景。從基礎的@Tag、@Operation到高級的@SecurityScheme、@Callback，每個注解都配有清晰的代碼示例和實際應用案例。包含全局配置、多安全方案、復雜響應結構、Webhook回調等企業級場景，幫助你構建專業級的API文檔系統。

一、注解介紹

1. API 基本信息與分組注解

這些注解用于描述整個API或對接口進行分組，通常用在控制器類上。

注解	適用范圍	屬性	說明	示例
`@Tag`	類	`name` ：（必填）標簽名稱。 `description`：標簽描述。	用于對API操作進行邏輯分組。一個控制器可以有多個標簽。在Swagger UI中顯示為不同的分類。	`@Tag(name = "用戶管理", description = "用戶的增刪改查API")`
`@Hidden`	類、方法	無	隱藏被注解的類或方法，不會出現在生成的API文檔中。	`@Hiddenpublic class InternalController { ... }`

2. 接口操作注解 (Operation Annotations)

這些注解用于描述具體的HTTP接口，用在控制器方法上。

注解	適用范圍	屬性	說明	示例
`@Operation`	方法	`summary` ：操作摘要。 `description`：詳細描述。 `method`：指定HTTP方法（通常不需要，由`@GetMapping`等隱含）。 `tags`：覆蓋類級別的標簽，為該操作指定新的分組。	描述一個HTTP請求操作（如一個GET或POST端點），是方法上最重要的注解。	`@Operation(summary = "創建用戶", description = "根據傳入的用戶信息創建一個新用戶")`
`@ApiResponse`	方法	`responseCode` ：（必填） HTTP狀態碼，如 "200", "404"。 `description`：響應的描述。 `content`：指定響應內容（使用`@Content`）。	聲明一個操作可能返回的響應。通常與`@Operation`的`responses`屬性一起使用，描述各種可能的返回結果。	`@ApiResponse(responseCode = "404", description = "用戶不存在")`
`@ApiResponses`	方法	`value` ：一個`@ApiResponse`注解的數組。	當需要聲明多個響應時，用它來包裹多個`@ApiResponse`。	`@ApiResponses(value = {@ApiResponse(responseCode = "200", ...),@ApiResponse(responseCode = "400", ...)})`
`@Callback`	方法	`name` ：回調名稱。 `callbackUrlExpression`：回調URL表達式。	描述一個回調操作，用于Webhooks等異步通知場景，使用相對較少。	(略復雜，此處不展開示例)

3. 參數注解 (Parameter Annotations)

這些注解用于描述接口的入參，可以用在方法參數上。

注解	適用范圍	屬性	說明	示例
`@Parameter`	參數	`description` ：參數描述。 `required`：是否必填，默認為`false`。 `example`：提供示例值。 `hidden`：是否隱藏該參數。 `schema`：指定參數的schema（使用`@Schema`）。	描述一個操作參數，如`@PathVariable`, `@RequestParam`, `@RequestHeader`, `@CookieValue`等。注意：`@RequestBody`參數通常不用此注解，而是用`@Schema`。	`public User getUserById(@Parameter(description = "用戶ID", example = "123", required = true)@PathVariable Long id) {...}`
`@Parameters`	方法	`value` ：一個`@Parameter`注解的數組。	當需要在方法上為多個參數添加描述時，用它來包裹多個`@Parameter`。	`@Parameters({@Parameter(name = "id", description = "ID"),@Parameter(name = "name", description = "名稱")})`
`@RequestHeader`	參數	與`@Parameter`屬性相同。	它是`@Parameter`的一個特殊化，專門用于描述請求頭參數，會在UI上被單獨分組顯示。	`@RequestHeader(@Parameter(description = "認證令牌", required = true)) String authToken`

4. 請求體與內容注解 (Request Body & Content)

這些注解用于描述復雜的請求或響應內容。

注解	適用范圍	屬性	說明	示例
`@RequestBody`	參數	`description` ：請求體的描述。 `required`：是否必填。 `content`：指定請求體的媒體類型和結構（使用`@Content`）。	專門用于描述`@RequestBody`參數。提供對請求體的詳細說明。	`@RequestBody(description = "用戶信息", required = true, content = @Content(schema = @Schema(implementation = User.class))) User user`
`@Content`	與`@RequestBody`或`@ApiResponse`的`content`屬性一起使用	`schema` ：指定內容的schema（使用`@Schema`）。 `mediaType`：指定媒體類型，如 "application/json"。 `examples`：提供多個示例（使用`@ExampleObject`）。	定義請求或響應體的媒體類型和結構。	`content = @Content(mediaType = "application/json", schema = @Schema(implementation = User.class))`
`@Schema`	模型類、模型屬性、參數	`description` ：描述。 `example`：提供示例值。 `requiredMode`：指定是否必須（`Schema.RequiredMode.REQUIRED`）。 `implementation`：指定關聯的類（用于在`@Content`中）。 `allowableValues`：限制允許的值。	這是最重要的模型注解。用于描述DTO（數據傳輸對象）、VO（值對象）等模型，或修飾`@RequestBody`/響應體的結構。	`@Schema(description = "用戶實體", requiredMode = Schema.RequiredMode.REQUIRED)public class User {@Schema(description = "用戶ID", example = "1")private Long id;}`

5. 安全方案注解 (Security Annotations)

用于描述API的認證和授權方式。

注解	適用范圍	屬性	說明	示例
`@SecurityScheme`	類（配置類）	`type` ：安全方案類型（如`SecurityScheme.Type.HTTP`）。 `scheme`：方案（如 "bearer"）。 `bearerFormat`：承載格式（如 "JWT"）。 `name`：方案名稱（用于`@SecurityRequirement`）。 `in`：ApiKey類型時，token的位置（`SecurityScheme.In.HEADER`）。	在配置類中定義全局的安全方案，如JWT、OAuth2、ApiKey等。	見下方配置示例
`@SecurityRequirement`	類、方法	`name` ：引用的安全方案名稱。 `scopes`：所需的OAuth作用域（數組）。	聲明一個操作或整個控制器需要哪些安全方案。在Swagger UI中會出現Authorize按鈕。	`@SecurityRequirement(name = "bearerAuth")`

安全配置示例：

@Configuration
@SecurityScheme( // 定義安全方案
  name = "bearerAuth",
  type = SecurityScheme.Type.HTTP,
  scheme = "bearer",
  bearerFormat = "JWT"
)
publicclass OpenApiConfig {}

@RestController
@SecurityRequirement(name = "bearerAuth") // 整個控制器都需要認證
@Tag(name = "Secure API")
class SecureController {
    @GetMapping("/secure")
    public String secureEndpoint() {
        return"This is secure!";
    }
}

二、swagger注解使用案例

1. 全局配置類 (OpenAPIConfig.java)

package com.example.config;

import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
@SecurityScheme( // 定義全局安全方案
    name = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT",
    description = "JWT認證令牌，格式: Bearer {token}"
)
publicclass OpenAPIConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        returnnew OpenAPI()
            .info(new Info()
                .title("企業級應用API文檔")
                .version("1.0.0")
                .description("""
                    這是企業級應用的完整API文檔，包含：
                    - 用戶管理系統
                    - 電商訂單系統  
                    - 文件服務系統
                    """)
                .contact(new Contact()
                    .name("技術支持")
                    .email("support@company.com")
                    .url("https://support.company.com"))
                .license(new License()
                    .name("Apache 2.0")
                    .url("https://www.apache.org/licenses/LICENSE-2.0")))
            .addSecurityItem(new SecurityRequirement().addList("bearerAuth")); // 全局安全要求
    }
}

2. 安全配置類

@Configuration
@SecuritySchemes({ // 使用 @SecuritySchemes 包裹多個 @SecurityScheme
    @SecurityScheme(
        name = "JWT",
        type = SecuritySchemeType.HTTP,
        scheme = "bearer",
        bearerFormat = "JWT",
        description = "JWT認證令牌"
    ),
    @SecurityScheme(
        name = "APIKey",
        type = SecuritySchemeType.APIKEY,
        in = SecuritySchemeIn.HEADER,
        paramName = "X-API-KEY",
        description = "API密鑰認證"
    ),
    @SecurityScheme(
        name = "OAuth2",
        type = SecuritySchemeType.OAUTH2,
        flows = @OAuthFlows( // 使用 @OAuthFlows 和 @OAuthFlow
            authorizationCode = @OAuthFlow(
                authorizationUrl = "https://example.com/oauth/authorize",
                tokenUrl = "https://example.com/oauth/token",
                scopes = {
                    @OAuthScope(name = "read", description = "讀取權限"),
                    @OAuthScope(name = "write", description = "寫入權限")
                }
            )
        )
    ),
    @SecurityScheme(
        name = "BasicAuth",
        type = SecuritySchemeType.HTTP,
        scheme = "basic",
        description = "基礎認證"
    )
})
publicclass SecurityConfig {
}

3. 控制器

@RestController
@RequestMapping("/api/v1/comprehensive")
@Tag(name = "綜合演示API", description = "展示所有Swagger注解的用法")
@SecurityRequirement(name = "JWT")
publicclass ComprehensiveController {

    // 1. 演示所有參數類型
    @PostMapping("/all-params/{pathVar}")
    @Operation(summary = "所有參數類型演示")
    @Parameters({
        @Parameter(name = "pathVar", description = "路徑參數", in = ParameterIn.PATH, example = "123"),
        @Parameter(name = "queryParam", description = "查詢參數", in = ParameterIn.QUERY, example = "value"),
        @Parameter(name = "X-Custom-Header", description = "頭部參數", in = ParameterIn.HEADER, example = "header-value"),
        @Parameter(name = "sessionId", description = "Cookie參數", in = ParameterIn.COOKIE, example = "session-123")
    })
    public ResponseEntity<String> allParameterTypes(
        @PathVariable String pathVar,
        @RequestParam String queryParam,
        @RequestHeader("X-Custom-Header") String customHeader,
        @CookieValue("sessionId") String sessionId) {
        
        return ResponseEntity.ok("Success");
    }

    // 2. 演示數組和復雜Schema
    @PostMapping("/batch-create")
    @Operation(summary = "批量創建項目")
    public ResponseEntity<String> batchCreate(
        @io.swagger.v3.oas.annotations.parameters.RequestBody(
            description = "批量創建請求",
            content = @Content(
                mediaType = "application/json",
                array = @ArraySchema( // 使用 @ArraySchema
                    schema = @Schema(implementation = User.class),
                    minItems = 1,
                    maxItems = 100
                ),
                examples = @ExampleObject(
                    value = """
                        [
                          {"username": "user1", "email": "user1@example.com"},
                          {"username": "user2", "email": "user2@example.com"}
                        ]
                        """
                )
            )
        )
        @RequestBody List<@Valid User> users) {
        
        return ResponseEntity.ok("Batch created");
    }

    // 3. 演示多安全方案
    @GetMapping("/sensitive-data")
    @Operation(summary = "獲取敏感數據")
    @SecurityRequirement(name = "JWT") // 方法級別安全要求
    @SecurityRequirement(name = "APIKey") // 多個安全要求
    public ResponseEntity<Map<String, String>> getSensitiveData() {
        return ResponseEntity.ok(Map.of("data", "sensitive information"));
    }

    // 4. 演示復雜響應
    @GetMapping("/complex-response")
    @Operation(summary = "復雜響應結構")
    @ApiResponses({
        @ApiResponse(
            responseCode = "200",
            description = "成功響應",
            content = {
                @Content(
                    mediaType = "application/json",
                    schema = @Schema(implementation = ComplexResponse.class),
                    examples = {
                        @ExampleObject(
                            name = "success_example",
                            summary = "成功示例",
                            value = """
                                {
                                  "status": "SUCCESS",
                                  "data": {
                                    "users": [
                                      {"id": 1, "name": "John"},
                                      {"id": 2, "name": "Jane"}
                                    ],
                                    "metadata": {
                                      "page": 1,
                                      "total": 2
                                    }
                                  }
                                }
                                """
                        ),
                        @ExampleObject(
                            name = "error_example",
                            summary = "錯誤示例",
                            value = """
                                {
                                  "status": "ERROR",
                                  "message": "數據不存在"
                                }
                                """
                        )
                    }
                ),
                @Content(
                    mediaType = "application/xml",
                    schema = @Schema(implementation = ComplexResponse.class)
                )
            }
        ),
        @ApiResponse(
            responseCode = "403",
            description = "權限不足",
            content = @Content(schema = @Schema(implementation = ErrorResponse.class))
        )
    })
    public ResponseEntity<ComplexResponse> getComplexResponse() {
        return ResponseEntity.ok(new ComplexResponse());
    }

    // 5. 演示隱藏特定端點
    @GetMapping("/internal/stats")
    @io.swagger.v3.oas.annotations.Hidden // 隱藏內部端點
    public ResponseEntity<String> getInternalStats() {
        return ResponseEntity.ok("Internal statistics");
    }
}

4. 模型類

@Data
@Schema(
    description = "用戶實體",
    requiredProperties = {"username", "email"}, // 必需屬性
    accessMode = Schema.AccessMode.READ_WRITE
)
publicclass User {
    
    @Schema(
        description = "用戶ID",
        example = "1",
        accessMode = Schema.AccessMode.READ_ONLY,
        minimum = "1"
    )
    private Long id;

    @Schema(
        description = "用戶名",
        example = "john_doe",
        minLength = 3,
        maxLength = 50,
        pattern = "^[a-zA-Z0-9_]+$"
    )
    private String username;

    @Schema(
        description = "郵箱地址",
        example = "john@example.com",
        format = "email",
        maxLength = 100
    )
    private String email;

    @Schema(
        description = "用戶年齡",
        example = "25",
        minimum = "0",
        maximum = "150",
        exclusiveMinimum = true,
        exclusiveMaximum = true
    )
    private Integer age;

    @Schema(
        description = "用戶狀態",
        example = "ACTIVE",
        allowableValues = {"ACTIVE", "INACTIVE", "SUSPENDED"},
        defaultValue = "ACTIVE"
    )
    private String status;

    @Schema(
        description = "標簽列表",
        example = "["vip", "new_user"]",
        maxItems = 10
    )
    private List<String> tags;

    @Schema(
        description = "元數據",
        example = "{"key": "value"}",
        additionalProperties = Schema.AdditionalPropertiesValue.TRUE
    )
    private Map<String, Object> metadata;

    @Schema(
        description = "創建時間",
        example = "2023-10-01T12:00:00",
        accessMode = Schema.AccessMode.READ_ONLY
    )
    private LocalDateTime createdAt;
}

@Data
@Schema(description = "復雜響應結構")
class ComplexResponse {
    
    @Schema(
        description = "響應狀態",
        example = "SUCCESS",
        allowableValues = {"SUCCESS", "ERROR"}
    )
    private String status;

    @Schema(
        description = "響應數據",
        oneOf = {User.class, Product.class} // 使用 oneOf
    )
    private Object data;

    @Schema(
        description = "分頁信息",
        allOf = {Pagination.class} // 使用 allOf
    )
    private Object pagination;
}

@Data
@Schema(description = "分頁信息")
class Pagination {
    @Schema(description = "當前頁碼", example = "1")
    privateint page;
    
    @Schema(description = "每頁大小", example = "20")
    privateint size;
    
    @Schema(description = "總記錄數", example = "100")
    privatelong total;
}

@Data
@Schema(description = "錯誤響應")
class ErrorResponse {
    @Schema(description = "錯誤代碼", example = "403")
    privateint code;
    
    @Schema(description = "錯誤信息", example = "權限不足")
    private String message;
    
    @Schema(description = "時間戳", example = "2023-10-01T12:00:00")
    private LocalDateTime timestamp;
}

5. 回調控制器

@RestController
@RequestMapping("/api/v1/webhook")
@Tag(name = "Webhook管理", description = "Webhook回調接口")
publicclass WebhookController {

    @PostMapping("/subscribe")
    @Operation(summary = "訂閱Webhook")
    @Callbacks({
        @Callback(
            name = "onEvent",
            callbackUrlExpression = "http://localhost:8080/api/v1/webhook/event",
            operation = @Operation(
                method = "POST",
                description = "事件回調",
                requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
                    content = @Content(
                        schema = @Schema(implementation = WebhookEvent.class)
                    )
                ),
                responses = @ApiResponse(
                    responseCode = "200",
                    description = "回調處理成功"
                )
            )
        )
    })
    public String subscribeWebhook() {
        return"Subscription created";
    }
}

@Schema(description = "Webhook事件")
class WebhookEvent {
    @Schema(description = "事件類型", example = "user.created")
    private String type;
    
    @Schema(description = "事件數據")
    private Object data;
    
    @Schema(description = "時間戳", example = "2023-10-01T12:00:00")
    private String timestamp;
}

6. Swagger注解總結

這個完整的案例包含了所有核心的Swagger注解：

6.1. 基本信息與分組

@Tag - API分組
@Hidden - 隱藏API

6.2. 接口操作

@Operation - 操作描述
@ApiResponse - 單個響應
@ApiResponses - 多個響應
@Callback / @Callbacks - 回調操作

6.3. 參數描述

@Parameter - 參數描述
@Parameters - 多個參數
所有 in 類型：PATH, QUERY, HEADER, COOKIE

6.4. 請求體與內容

@RequestBody - 請求體描述
@Content - 內容類型
@Schema - 數據模型
@ArraySchema - 數組結構
@ExampleObject - 示例對象

6.5. 安全方案

@SecurityScheme - 安全方案定義
@SecuritySchemes - 多個安全方案
@SecurityRequirement - 安全要求
所有安全類型：HTTP, APIKEY, OAUTH2, OPENIDCONNECT
@OAuthFlows / @OAuthFlow / @OAuthScope - OAuth2流程

6.6. Schema高級特性

oneOf / allOf - 組合模式
accessMode - 訪問模式
requiredMode - 必需模式
allowableValues - 允許值
format - 數據格式
pattern - 正則模式
minimum / maximum - 數值范圍
minLength / maxLength - 長度限制
minItems / maxItems - 數組限制

責任編輯：武曉燕來源： Solomon肖哥談架構