Swagger复用枚举报错：不应存在额外属性schema

你的报错原因是在Project对象的registry属性中，错误地把$ref嵌套在了schema字段下，同时还保留了type: string——这违反了OpenAPI规范：

• schema不是属性定义里的合法字段，这就是报错提示“should NOT have additional properties”的直接原因
• 当使用$ref引用已有schema时，不需要再重复写type（被引用的Registry已经定义了type: string）

修正后的Project部分代码如下：

Project:
  required:
    - name
    - registry
  type: object
  properties:
    name:
      type: string
      example: "Project 1"
    registry:
      $ref: '#/components/schemas/Registry'
      example: "My Registry 1"  # 可选：如果需要在这里单独指定示例，保留即可；也可以把示例移到Registry的定义里

完整修正后的Swagger文件：

openapi: 3.0.3
info:
  title: My API
  description: |-
    Blah
  contact:
    email: support@example.com
  version: 1.0.0
externalDocs:
  description: Find out more about blah
  url: http://blah.io
paths:
  /credits-received:
    post:
      tags:
        - Credits Received
      operationId: creditsReceived
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditsReceivedData'
        required: true
      responses:
        '200':
          description: Successful operation

components:
  schemas:
    CreditsReceivedData:
      required:
        - project
      type: object
      properties:
        project:
          $ref: '#/components/schemas/Project'

    Project:
      required:
        - name
        - registry
      type: object
      properties:
        name:
          type: string
          example: "Project 1"
        registry:
          $ref: '#/components/schemas/Registry'
          example: "My Registry 1"
    Registry:
      type: string
      enum:
        - My Registry 1
        - My registry 2

这样修改后，就可以正确引用可复用的枚举Registry，同时消除结构错误。

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