如何在OpenAPI YAML Schema中重命名additionalProperties

问题背景 #

现有一个OpenAPI 3.0.1的YAML描述文件，API功能正常，但希望在保持API语义正确的前提下，让Schema里的额外属性集合在文档展示和代码生成时，使用代码中实际的名称CustomName（对应代码结构里的Dictionary<string, string> CustomName）。尝试过别名方案，但因为additionalProperties是OpenAPI关键字，无法直接重命名。

原YAML内容：

openapi: 3.0.1
info:
  title: exampleApp
  version: 1.0.0
paths:
  /example:
    post:
      requestBody:
        content:
            application/json:
              schema:
                $ref: "#/components/schemas/Example"
      responses:
        '200':
          description: >
            Success.
          content:
            application/json:
              schema:
                type: string

components:
  schemas:
    Example:
      type: object
      properties:
        name: 
          type: string
        prop1:
          type: string
        additionalProperties:
          type: string

期望生成的代码结构：

{
  string name;
  string prop1;
  Dictionary<string, string> CustomName;
}

解决方案 #

核心思路是保留OpenAPI关键字的语义正确性，同时通过扩展字段实现代码命名映射，再通过文档说明提升可读性：

1. 修改后的YAML示例 #

openapi: 3.0.1
info:
  title: exampleApp
  version: 1.0.0
paths:
  /example:
    post:
      requestBody:
        content:
            application/json:
              schema:
                $ref: "#/components/schemas/Example"
      responses:
        '200':
          description: >
            Success.
          content:
            application/json:
              schema:
                type: string

components:
  schemas:
    Example:
      type: object
      properties:
        name: 
          type: string
        prop1:
          type: string
      # 保留additionalProperties，确保API能正确处理额外JSON属性
      additionalProperties:
        type: string
      # 指定代码生成时的字段名称（适配OpenAPI Generator等主流工具）
      x-codegen-name: CustomName
      # 文档说明，明确对应代码中的字段
      description: |
        包含固定属性name、prop1，以及自定义键值对集合（对应代码中的CustomName字段，类型为Dictionary<string, string>）

2. 关键说明 #

• 保留additionalProperties：这个关键字是OpenAPI定义对象额外属性的标准方式，不能修改或删除，否则会破坏API的结构校验逻辑。
• x-codegen-name: CustomName：这是代码生成器（如OpenAPI Generator）支持的扩展字段，会指示生成代码时将额外属性集合映射为CustomName字段，完全匹配你需要的代码结构。
• 文档描述：通过description字段在API文档中明确标注该部分对应代码中的字段名称，让文档读者直接理解映射关系。

如果使用的是其他代码生成工具，可能需要替换为对应工具的扩展字段（比如Swagger Codegen用x-swagger-codegen-name），但x-codegen-name是目前最通用的选择。

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