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

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

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認(rèn)證令牌，格式: Bearer {token}"
)
publicclass OpenAPIConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        returnnew OpenAPI()
            .info(new Info()
                .title("企業(yè)級(jí)應(yīng)用API文檔")
                .version("1.0.0")
                .description("""
                    這是企業(yè)級(jí)應(yīng)用的完整API文檔，包含：
                    - 用戶管理系統(tǒng)
                    - 電商訂單系統(tǒng)  
                    - 文件服務(wù)系統(tǒng)
                    """)
                .contact(new Contact()
                    .name("技術(shù)支持")
                    .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")); // 全局安全要求
    }
}

@Configuration
@SecuritySchemes({ // 使用 @SecuritySchemes 包裹多個(gè) @SecurityScheme
    @SecurityScheme(
        name = "JWT",
        type = SecuritySchemeType.HTTP,
        scheme = "bearer",
        bearerFormat = "JWT",
        description = "JWT認(rèn)證令牌"
    ),
    @SecurityScheme(
        name = "APIKey",
        type = SecuritySchemeType.APIKEY,
        in = SecuritySchemeIn.HEADER,
        paramName = "X-API-KEY",
        description = "API密鑰認(rèn)證"
    ),
    @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 = "讀取權(quán)限"),
                    @OAuthScope(name = "write", description = "寫(xiě)入權(quán)限")
                }
            )
        )
    ),
    @SecurityScheme(
        name = "BasicAuth",
        type = SecuritySchemeType.HTTP,
        scheme = "basic",
        description = "基礎(chǔ)認(rèn)證"
    )
})
publicclass SecurityConfig {
}

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

    // 1. 演示所有參數(shù)類型
    @PostMapping("/all-params/{pathVar}")
    @Operation(summary = "所有參數(shù)類型演示")
    @Parameters({
        @Parameter(name = "pathVar", description = "路徑參數(shù)", in = ParameterIn.PATH, example = "123"),
        @Parameter(name = "queryParam", description = "查詢參數(shù)", in = ParameterIn.QUERY, example = "value"),
        @Parameter(name = "X-Custom-Header", description = "頭部參數(shù)", in = ParameterIn.HEADER, example = "header-value"),
        @Parameter(name = "sessionId", description = "Cookie參數(shù)", 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. 演示數(shù)組和復(fù)雜Schema
    @PostMapping("/batch-create")
    @Operation(summary = "批量創(chuàng)建項(xiàng)目")
    public ResponseEntity<String> batchCreate(
        @io.swagger.v3.oas.annotations.parameters.RequestBody(
            description = "批量創(chuàng)建請(qǐng)求",
            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 = "獲取敏感數(shù)據(jù)")
    @SecurityRequirement(name = "JWT") // 方法級(jí)別安全要求
    @SecurityRequirement(name = "APIKey") // 多個(gè)安全要求
    public ResponseEntity<Map<String, String>> getSensitiveData() {
        return ResponseEntity.ok(Map.of("data", "sensitive information"));
    }

    // 4. 演示復(fù)雜響應(yīng)
    @GetMapping("/complex-response")
    @Operation(summary = "復(fù)雜響應(yīng)結(jié)構(gòu)")
    @ApiResponses({
        @ApiResponse(
            responseCode = "200",
            description = "成功響應(yīng)",
            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 = "錯(cuò)誤示例",
                            value = """
                                {
                                  "status": "ERROR",
                                  "message": "數(shù)據(jù)不存在"
                                }
                                """
                        )
                    }
                ),
                @Content(
                    mediaType = "application/xml",
                    schema = @Schema(implementation = ComplexResponse.class)
                )
            }
        ),
        @ApiResponse(
            responseCode = "403",
            description = "權(quán)限不足",
            content = @Content(schema = @Schema(implementation = ErrorResponse.class))
        )
    })
    public ResponseEntity<ComplexResponse> getComplexResponse() {
        return ResponseEntity.ok(new ComplexResponse());
    }

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

@Data
@Schema(
    description = "用戶實(shí)體",
    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 = "用戶狀態(tài)",
        example = "ACTIVE",
        allowableValues = {"ACTIVE", "INACTIVE", "SUSPENDED"},
        defaultValue = "ACTIVE"
    )
    private String status;

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

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

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

@Data
@Schema(description = "復(fù)雜響應(yīng)結(jié)構(gòu)")
class ComplexResponse {
    
    @Schema(
        description = "響應(yīng)狀態(tài)",
        example = "SUCCESS",
        allowableValues = {"SUCCESS", "ERROR"}
    )
    private String status;

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

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

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

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

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

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

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