Swagger 3.0 提供了豐富的注解來詳細描述 API 的請求和響應。以下是一個使用 @Operation、@Parameter、@RequestBody 和 @ApiResponse 注解的示例，展示了如何設置請求頭、請求參數、路徑變量、請求體和響應體。代碼中未使用 DTO 對象，而是使用 Map 來傳遞參數和響應。通過 @Parameter 注解，可以定義查詢參數、路徑變量和請求頭。@RequestBody 注解用于描述請求體的結構，而 @ApiResponse 注解則用于定義成功的響應內容。此示例展示了如何在 Swagger 中詳細描述 API 的各個部分，幫助開發者理解和使用 API。

為了演示如何詳細設置每個請求頭、請求參數、路徑變量、請求體、響應體，下面的代碼沒有使用 DTO 對象，參數和響應都使用的 Map。

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.StringToClassMapItem;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;import java.util.Map;@RestController
@RequestMapping("/api/swagger/example")
@Tag(name = "Swagger測試", description = "提供用戶的基本增刪查操作")
public class SwaggerExampleController {@PostMapping("/create/{tenantId}")@Operation(summary = "創建新用戶",description = "根據請求體中的參數創建一個新用戶，返回創建的用戶信息",parameters = {@Parameter(name = "type",description = "參數type",in = ParameterIn.QUERY,schema = @Schema(type = "string", example = "T001")),@Parameter(name = "tenantId",in = ParameterIn.PATH,schema = @Schema(type = "string", example = "tenant-001")),@Parameter(name = "Authorization",description = "認證令牌",required = true,in = ParameterIn.HEADER,schema = @Schema(type = "string", example = "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")),@Parameter(name = "Request-Id",description = "請求追蹤ID",required = true,in = ParameterIn.HEADER,schema = @Schema(type = "string", example = "req-123456789"))},requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(required = true,description = "用戶信息，包括用戶名和郵箱",content = @Content(mediaType = "application/json",schema = @Schema(type = "object",requiredProperties = {"name", "email"},properties = {@StringToClassMapItem(key = "name",value = String.class),@StringToClassMapItem(key = "email",value = String.class)}))),responses = {@ApiResponse(responseCode = "200", description = "用戶創建成功",content = @Content(mediaType = "application/json",schema = @Schema(type = "object",properties = {@StringToClassMapItem(key = "id", value = Long.class),@StringToClassMapItem(key = "name", value = String.class),@StringToClassMapItem(key = "email", value = String.class),@StringToClassMapItem(key = "tenantId", value = String.class),@StringToClassMapItem(key = "authorization", value = String.class),@StringToClassMapItem(key = "requestId", value = String.class)})))})public Map<String, Object> create(@RequestParam("type") String type,@PathVariable("tenantId") String tenantId,@RequestHeader("Authorization") String authorization,@RequestHeader("Request-Id") String requestId,@RequestBody Map<String, Object> userMap) {userMap.put("type", type);userMap.put("id", 1001L); // 模擬生成的IDuserMap.put("tenantId", tenantId); // 添加租戶IDuserMap.put("authorization", authorization);userMap.put("requestId", requestId);return userMap;}}

---

（END）