为 Java 对象配置 OpenAPI 示例值（支持嵌套对象）-java教程-PHP中文网

为 Java 对象配置 OpenAPI 示例值（支持嵌套对象）

本文详解如何在 Springdoc OpenAPI（Swagger 3）中为 Java 实体类及其嵌套对象字段正确设置 JSON 格式的示例值（example），避免字符串转义问题，确保生成的 OpenAPI 文档中 example 字段为合法 JSON 对象而非字符串。

本文详解如何在 springdoc openapi（swagger 3）中为 java 实体类及其嵌套对象字段正确设置 json 格式的示例值（example），避免字符串转义问题，确保生成的 openapi 文档中 `example` 字段为合法 json 对象而非字符串。

在使用 Springdoc OpenAPI 生成 API 文档时，@Schema 注解的 example 属性是定义字段示例值的关键。但需特别注意：example 接收的是字符串字面量，OpenAPI 规范要求该字符串必须是合法 JSON 的序列化形式——即它本身是 JSON 字符串，而非 Java 字符串字面量。若直接写 example = "{'age': 30}"，生成的 OpenAPI JSON 中会保留外层引号，导致 "example": "{'age': 30}"（非法 JSON），而非期望的 "example": {"age": 30}。

✅ 正确做法是：将嵌套对象的示例写为标准 JSON 字符串（双引号、无多余空格或语法错误），并确保 Java 字符串中正确转义双引号。例如：

@Schema(description = "The person.", type = "object", example = "{ \"name\": \"John\", \"age\": 30 }")
private Person person;

此处 example 值是一个 Java 字符串，其内容是符合 JSON 规范的对象字面量 { "name": "John", "age": 30 }。Springdoc 在序列化为 OpenAPI JSON 时，会原样嵌入该 JSON 片段（不加额外引号），最终生成：

"example": {
  "name": "John",
  "age": 30
}

⚠️ 注意事项：

js2java

JavaScript 到 Java 全栈翻译助手，专为前端开发者学习 Java 或快速实现后端业务逻辑而设计。当用户提到以下场景时必须使用此技能： - "帮我把这段 JS 代码转成 Java" - "用 Java 怎么写这个逻辑" - "我习惯用 JS 写，想翻译成 Java" - "教我 Java，我要写后端接...

下载

必须使用双引号（"）包裹 JSON 键和字符串值，单引号（'）不符合 JSON 标准；
Java 字符串内双引号需用反斜杠转义：\"；
数值（如 30）无需引号；布尔值用 true/false，不要加引号；
若 Person 类本身也标注了 @Schema 并定义了 example，优先级低于字段级 @Schema.example，因此推荐在关联字段处显式声明；
对于复杂嵌套（如 List<person></person> 或含枚举、日期字段的对象），建议先用工具校验 JSON 合法性，再填入 example。

? 进阶技巧：若示例结构复杂或需复用，可借助 @Schema#ref 引用外部定义，或通过 @io.swagger.v3.oas.annotations.media.ExampleObject 配合 @Schema#examples 提供多个示例（适用于 OpenAPI 3.1+）。但对于单个典型对象示例，直接使用 example 字符串是最简洁可靠的方式。

综上，为嵌套对象设置 OpenAPI 示例的核心在于：写对 JSON，转义好引号，信规范而非直觉。