swagger - OpenAPI 3.0 - 如何避免在通过 ref 包含示例时添加 "value" key

Question

使用 OpenAPI 有没有一种方法可以通过 $ref: 标签引用示例，而不需要添加“值”键？

查看我添加到 petstore.yaml 中的示例:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:

  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Pets"
              example:
                $ref: "#/components/examples/animals"

        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /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"
              example:
                $ref: "#/components/examples/garfield"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

  examples:
    garfield:
      id: 1
      name: garfield
      tag: cat
    grumpycat:
      id: 2
      name: grumpycat
      tag: cat
    odie:
      id: 3
      name: odie
      tag: dog
    animals:
      - $ref: "#/components/examples/garfield"
      - $ref: "#/components/examples/grumpycat"
      - $ref: "#/components/examples/odie"

openapi-generator-cli validate 说它是无效的 OpenAPI，我的 VSCode OpenAPI 插件也是如此。错误日志输出:

Validating spec (/local/petstore.yaml)
Errors:
    -attribute components.examples.odie.name is unexpected
    -attribute components.examples.garfield.id is unexpected
    -attribute components.examples.grumpycat.name is unexpected
    -attribute components.examples.animals is not of type `object`
    -attribute components.examples.garfield.tag is unexpected
    -attribute components.examples.garfield.name is unexpected
    -attribute components.examples.odie.tag is unexpected
    -attribute components.examples.grumpycat.id is unexpected
    -attribute components.examples.grumpycat.tag is unexpected
    -attribute components.examples.odie.id is unexpected

[错误] 规范有 10 个错误。

我可以通过像这样添加值键来更正错误:

  examples:
    garfield:
      value:
        id: 1
        name: garfield
        tag: cat
    grumpycat:
      value:
        id: 2
        name: grumpycat
        tag: cat
    odie:
      value:
        id: 3
        name: odie
        tag: dog
    animals:
      value:
        - $ref: "#/components/examples/garfield"
        - $ref: "#/components/examples/grumpycat"
        - $ref: "#/components/examples/odie"

问题在于，我的示例现在包含 value 属性，我不想要它，因为它不是架构的一部分:

{
    "value": {
        "id": 1,
        "name": "garfield",
        "tag": "cat"
    }
}

问题:有没有办法像我在不使用引入“值”属性的情况下那样通过 $ref 定义示例？

Answer 1

正确的语法如下:

components:
  examples:
    garfield:
      value:
        id: 1
        name: garfield
        tag: cat
    grumpycat:
      value:
        id: 2
        name: grumpycat
        tag: cat
    odie:
      value:
        id: 3
        name: odie
        tag: dog
    animals:
      summary: An array of two animals
      value:
        - id: 1
          name: garfield
          tag: cat
        - id: 2
          name: grumpycat
          tag: cat

paths:
  /pets:
    get:
      ...
      responses:
        '200':
          description: A paged array of pets
          ...
          content:
            application/json:    
              schema:
                $ref: "#/components/schemas/Pets"
              examples:
                animals:
                  $ref: "#/components/examples/animals"

  /pets/{petId}:
    get:
      ...
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
              examples:
                garfield:
                  $ref: "#/components/examples/garfield"
                grumpycat:
                  $ref: '#/components/examples/grumpycat'
                odie:
                  $ref: '#/components/examples/odie'

解释:

• components/examples 部分中的示例必须使用 Example Object句法。也就是说，实际示例值必须包装到 value 键中。

• 要从 components/examples 部分引用示例，您必须使用 examples 关键字(复数；不是单数 example) . examples 在参数和媒体类型中受支持，但在模式中不受支持。

• 在文字示例值中，不支持 $ref。也就是说，您不能 $ref 示例的一部分。