如何为OpenAPI规范中的所有模型名称添加统一前缀？

需求说明 #

要实现的是：自动修改OpenAPI YAML规范文件里的所有schemas名称，给它们加上指定前缀；同时要修正所有相关引用，包括路径里的$ref、discriminator的mapping等；最终输出修改后的YAML文件，不改动生成的Java模型，仅调整规范文件用于团队共享。

推荐工具方案 #

优先选择Java生态下的工具，推荐两种方式：

• OpenAPI Generator Maven插件：可以通过自定义扩展或transformer功能，在处理OpenAPI规范时自动重命名schemas并更新所有引用。
• Swagger Parser + 自定义Java代码：用Swagger Parser加载YAML文件，遍历所有schemas节点，完成重命名后，逐一更新所有$ref引用和discriminator的mapping，最后重新写入YAML。这种方式灵活性最高，能覆盖所有复杂场景。

效果示例 #

原OpenAPI YAML文件 #

openapi: "3.0.1"
info:
  title: "Pet clinic"
  version: "1.0"
paths:
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
        - some_complex_field
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
        some_complex_field:
          $ref: "#/components/schemas/ObjectWithInheritance"
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    ObjectWithInheritance:
      type: object
      properties:
        objectType:
          type: string
      required:
        - objectType
      discriminator:
        propertyName: objectType
        mapping:
          Cash: Cash
          Internal: Internal
    Cash:
      allOf:
        - $ref: '#/components/schemas/ObjectWithInheritance'
        - type: object
          properties:
            currencyCode:
              $ref: '#/components/schemas/CurrencyCode'
          required:
            - currencyCode
    CurrencyCode:
      type: string
    Internal:
      allOf:
        - $ref: '#/components/schemas/ObjectWithInheritance'
        - type: object
          properties:
            identifier:
              type: string
          required:
            - identifier

添加Prefixed前缀后的修改文件 #

openapi: "3.0.1"
info:
  title: "Pet clinic"
  version: "1.0"
paths:
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrefixedPet"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrefixedError"
components:
  schemas:
    PrefixedPet:
      type: object
      required:
        - id
        - name
        - some_complex_field
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
        some_complex_field:
          $ref: "#/components/schemas/PrefixedObjectWithInheritance"
    PrefixedPets:
      type: array
      items:
        $ref: "#/components/schemas/PrefixedPet"
    PrefixedError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    PrefixedObjectWithInheritance:
      type: object
      properties:
        objectType:
          type: string
      required:
        - objectType
      discriminator:
        propertyName: objectType
        mapping:
          Cash: PrefixedCash
          Internal: PrefixedInternal
    PrefixedCash:
      allOf:
        - $ref: '#/components/schemas/PrefixedObjectWithInheritance'
        - type: object
          properties:
            currencyCode:
              $ref: '#/components/schemas/PrefixedCurrencyCode'
          required:
            - currencyCode
    PrefixedCurrencyCode:
      type: string
    PrefixedInternal:
      allOf:
        - $ref: '#/components/schemas/PrefixedObjectWithInheritance'
        - type: object
          properties:
            identifier:
              type: string
          required:
            - identifier

核心处理要点 #

• 遍历components/schemas下的所有模型，给名称加上指定前缀
• 全局更新所有$ref引用路径，指向重命名后的模型
• 重点处理discriminator的mapping字段，将原模型名替换为带前缀的新名称
• 确保数组类型模型的items引用、嵌套模型的引用都同步修正

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