OpenAPI Maven插件生成Spring代码时属性错误排查

环境配置 #

• SpringBoot 3.4.1
• Java 21
• 目标：通过openapi-generator-maven-plugin生成Spring服务端Api及Model类

编译阶段遇到的错误 #

1. paths属性缺失：OpenAPI规范强制要求文档包含paths节点，否则无法通过校验
2. components.schemas.Error.properties、components.schemas.User.properties非object类型：Schema定义中properties字段被解析为非object类型，不符合规范要求

问题修复方案 #

1. 修正OpenAPI YAML文件的缩进与结构 #

YAML对缩进严格敏感，之前的缩进错误导致properties未被识别为object类型，同时遗漏了必填的paths节点。

错误示例（缩进错误+缺失paths）：

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
components:
  schemas:
    User:
      type: object
      properties
        id: integer
        name: string

修正后的正确示例：

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: 根据ID查询用户
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string

2. 补充Jackson依赖 #

SpringBoot 3.x 依赖Jackson处理JSON，OpenAPI Generator生成的Model类需要Jackson注解支持，需在pom.xml中添加以下依赖：

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
</dependency>

（SpringBoot父依赖已统一管理版本，无需手动指定版本号）

验证操作 #

执行Maven编译命令重新构建项目：

mvn clean compile

插件将正常生成Api接口类与Model实体类，编译无报错。

内容的提问来源于stack exchange，提问作者CoderJammer