OpenAPI 规范 - 鉴别器和 oneOf 的使用 - 光谱列表答案

【问题标题】：OpenAPI Specification - Use of Discriminator and oneOf - Spectral listingOpenAPI 规范 - 鉴别器和 oneOf 的使用 - 光谱列表
【发布时间】：2022-12-01 11:10:43
【问题描述】：

使用 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。

Animals 唯一的属性是 legs。鉴别器用于区分 Chicken 或 Dog，其中 Chicken 有 two legs 和 Dog 有 four 腿。

目标

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

问题

我认为使用鉴别器可能意味着带有twolegs的任何东西都是Chicken，而带有fourlegs的任何东西都是Dog。

我是不是弄错了，Dog拥有twolegs仍然是合法的，这就是它出错的原因？

我可以将其更改为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

【问题讨论】：

标签： openapi discriminator spectral

【解决方案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

【讨论】：