Search code examples
swaggeropenapiopenapi-generator

OpenAPI 3.0 - How to avoid adding "value" key when including examples by ref

With OpenAPI Is there a way to include examples by reference with the $ref: tag that doesn't not require adding the "value" key?

See examples I've added to the 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 says it's invalid OpenAPI as does my OpenAPI plugin for VSCode. Error log output:

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

[error] Spec has 10 errors.

I can correct the errors by adding a value key like this:

  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"

The problem with this is that, my examples now include the value property, which I don't want as it's not part of the schema:

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

Question: Is there a way for me to define the examples by $ref as I have done WITHOUT using introducing the "value" property?

Solution

  • The correct syntax is as follows:

    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'

    Explanation:

    • Examples in the components/examples section must use the Example Object syntax. That is, the actual example value must be wrapped into the value key.

    • To reference examples from the components/examples section, you must use the examples keyword (plural; not singular example). examples is supported in parameters and in media types, but not in schemas.

    • Within the literal example value, $ref is not supported. That is, you cannot $ref a part of an example.