openapi-generator-maven-plugin未生成@ExampleObject及Swagger UI示例求助

云原生阿岚

2026-7-26

解决方案

1. 修复插件配置中的拼写错误

你当前的插件配置里<skipOperationExample>标签的闭合标签拼写错误（少了字母t），这会导致该配置失效，默认会跳过示例生成。修正后的配置行应为：

<skipOperationExample>false</skipOperationExample>

2. 添加SpringDoc兼容配置以生成@ExampleObject

在插件的configOptions中添加以下配置，开启SpringDoc注解生成和模型示例生成：

<configOptions>
    <sourceFolder>src/gen/java/main</sourceFolder>
    <delegatePattern>true</delegatePattern>
    <interfaceOnly>true</interfaceOnly>
    <!-- 新增配置 -->
    <useSpringDoc>true</useSpringDoc>
    <generateModelExamples>true</generateModelExamples>
</configOptions>

useSpringDoc: 开启后生成SpringDoc兼容的注解（包括@ExampleObject）
generateModelExamples: 强制生成模型类的示例注解

3. 验证openapi.json中的示例定义

确保你的openapi.json中正确定义了示例字段，比如请求体或响应体的example/examples：

"paths": {
  "/your-api": {
    "post": {
      "requestBody": {
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/YourModel" },
            "example": {
              "id": 1,
              "name": "示例名称",
              "description": "示例描述"
            }
          }
        }
      },
      "responses": {
        "200": {
          "description": "成功响应",
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/YourModel" },
              "example": {
                "id": 1,
                "name": "返回示例名称",
                "description": "返回示例描述"
              }
            }
          }
        }
      }
    }
  }
}