OpenAPI 规范 - 鉴别器和 oneOf 的使用 - 频谱列表

Question

使用 oneOf 的 OpenAPI 鉴别器

使用带有 openApi 规范的鉴别器并使用 Spectral 进行 linting 的最小示例。

错误消息：

~/git/openapi_discriminator/openapi/v1/api.yaml
 22:23  error  oas3-valid-media-example  "example" property must match exactly one schema in oneOf  paths./discriminatortest.get.responses[200].content.application/json.example

具有简单 GET 方法的后台

OpenAPI 架构，该方法可以返回不同类型的 Animal。

定义了Animal 的子类，它可以是Chicken 或Dog。

动物唯一拥有的属性是腿。 鉴别器用于区分鸡或狗，其中鸡有两条腿 code> 和一条 狗 有四条 腿。

我的目的

是验证请求响应中的示例是否仅匹配一个模式。

问题

我认为使用鉴别器可能意味着任何具有 two legs 的东西都是 Chicken ，任何具有 four >legs 是一只狗。

我是否弄错了，狗拥有两条腿仍然是合法的，这就是它出错的原因？

我可以将其更改为 anyOf 但鉴别器就没用了？

代码

代码仓库 - openapi_discriminator

openapi_discriminator/openapi/v1/api.yaml：

openapi: "3.0.3"
info:
  title: Open API Discriminator Example
  version: "v1"

tags:
  - name: discriminator

paths:
  /discriminatortest:
    get:
      tags:
        - discriminator
      summary: Example using discriminator
      description: "Demonstrate a minimal example"
      responses:
        "200":
          description: Created
          content:
            application/json:
              schema: {$ref: "schemas.yaml#/components/schemas/Animal"}
              example:
                legs: "two"

openapi_discriminator/openapi/v1/schemas.yaml：

openapi: "3.0.3"

components:
  schemas:

    Animal:
      type: object
      discriminator:
        propertyName: legs
        mapping:
          two: Chicken
          four: Dog
      oneOf:
        - $ref: '#/components/schemas/Dog'
        - $ref: '#/components/schemas/Chicken'

    Chicken:
      type: object
      required:
        - legs
      properties:
        legs:
          type: string

    Dog:
      type: object
      required:
        - legs
      properties:
        legs:
          type: string

openapi_discriminator/openapi/.spectral.yml

extends: spectral:oas
rules:
  info-contact: false
  info-description: false
  oas3-api-servers: false
  openapi-tags: true
  operation-tags: true
  operation-operationId: false
  operation-description: true

运行 linting 命令：spectral lint "openapi/v1/api.yaml" --ruleset openapi/.spectral.yml

Answer 1

考虑到您很久以前就问过这个问题，不确定您是否仍在寻找答案。这里的问题是您没有明确声明腿的可用值。你知道，我也知道狗有四条腿，鸡有两条腿，但模式却没有。
换句话说，判别器必须仅根据 propertyName 的值进行判别，因此示例必须匹配该值。

添加enum值将解决您的问题：

openapi: "3.0.3"

components:
  schemas:

    Animal:
      type: object
      discriminator:
        propertyName: legs
        mapping:
          two: Chicken
          four: Dog
      oneOf:
        - $ref: '#/components/schemas/Dog'
        - $ref: '#/components/schemas/Chicken'

    Chicken:
      type: object
      required:
        - legs
      properties:
        legs:
          type: string
          enum:
            - two

    Dog:
      type: object
      required:
        - legs
      properties:
        legs:
          type: string
          enum:
            - four

此外，mapping现在对您来说可能不太有用：

          two: Chicken
          four: Dog

取决于您的用例，例如，如果您正在生成架构中的文档，这将意味着您生成的文档显示两个选项（“两个”和“四个”）。所以也许你可以考虑这样做：

          chicken: Chicken
          dog: Dog