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

w笔记--Swagger

backend 2025/7/27 20:14:36

遵循 OpenAPI 规范的 API 文档生成工具，支持接口涉违纪、文档化和测试。

自动生成文档、提供交互时测试（Swagger UI）、同步代码与文档。

依赖配置（添加 springdoc-openapi 依赖（OpenAPI 3.0 支持）：）

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.2.0</version>
</dependency>

配置类

@Configuration
public class OpenApiConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("用户服务 API").version("1.0.0").description("用户管理相关接口文档"));}
}

访问文档

Swagger UI：http://localhost:8080/swagger-ui.html

OpenAPI 规范 JSON：http://localhost:8080/v3/api-docs

核心注解（OpenAPI 3.0）

1.接口相关注解

@Tag 对接口进行分组

@Tag(name = "用户管理", description = "用户增删改查接口")

@Operation 描述单个接口的操作

@Operation(summary = "查询用户列表",description = "根据条件分页查询用户信息，支持姓名模糊搜索"
)

@Parameter 定义接口参数（路径、查询、请求体等）

@Parameter(name = "userDTO",description = "用户创建数据",required = true, //true为必填项content = @Content(schema = @Schema(implementation = UserCreateDTO.class))
)

2.数据模型注解

@Schema

2.1基本类型：描述实体类字段类型、示例、约束

@Data
@Schema(description = "用户信息响应对象")
public class UserVO {@Schema(description = "用户ID", example = "123", required = true)private Long id;@Schema(description = "用户名", example = "Alice", maxLength = 20)private String name;@Schema(description = "年龄", example = "25", minimum = "1", maximum = "150")private Integer age;
}

2.2 复杂结构

2.2.1 数组（List）

@Schema(type = "array",items = @Schema(implementation = UserVO.class),description = "用户列表"
)
private List<UserVO> users;

2.2.2 映射（Map）

@Schema(type = "object",additionalProperties = @Schema.AdditionalPropertiesValue(schema = @Schema(implementation = UserVO.class)),description = "用户映射（ID -> 用户信息）"
)
private Map<Long, UserVO> userMap;

2.2.3 嵌套对象

@Data
@Schema(description = "订单信息")
public class OrderVO {@Schema(description = "订单ID")private Long orderId;@Schema(description = "用户信息")private UserVO user; // 嵌套 UserVO@Schema(description = "商品列表")private List<ProductVO> products; // 嵌套数组
}

查看全文

http://www.xdnf.cn/news/9416.html