当前位置：首页 > news >正文

Swagger 3.0 中注解详细示例

news 2025/5/10 8:09:58

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;}}