Parser error on examples under response--should be allowed?

[johndunderhill]

The parser is giving an error on the examples node under a responses node:

Schema error at paths['/getlevelstatus.json/{learner}'].get.responses['200']
should NOT have additional properties
additionalProperty: examples

Seems like this should be allowed. Tested in the swagger online editor. The documentation generated looks correct at this indent level. Indenting more or less gives further errors, or the example is not rendered in the documentation.

Q	A
Bug or feature request?	Bug
Which Swagger/OpenAPI version?	3.0.0
Which Swagger-UI version?	editor.swagger.io
How did you install Swagger-UI?	NA
Which browser & version?	Version 60.0.3112.113 (Official Build) (64-bit)
Which operating system?	Windows 10

Demonstration API definition

openapi: 3.0.0
info:
  version: 0.0.1
  title: Tower API
  description: "Seems like this should be allowed."
  contact:
    name: John D. Underhill
    email: [email protected]
components:
  schemas:
    Tower:
      type: object
      properties:
        Status: 
          type: string
          enum: [Success, Failure]
        Data:
          type: string

paths:
  /getlevelstatus.json/{learner}:
    get:
      summary: Get level status
      operationId: getlevelstatus
      tags:
        - getlevelstatus
      description: Blah blah blah
      parameters:
      - in: path
        name: learner
        description: Blah blah blah
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tower'
          examples:
            example-one:
                Status: Success
                Data: Something

Configuration (browser query string, constructor, config.yaml)

Expected Behavior

By my reading of your documentation, examples should be aligned directly under 'schema' in this case (child of application/json), however that generates more parser errors, and the example is not rendered in the documentation. Here I've aligned it with content because that's the only solution that shows the example in the documentation. One of these possibilities should work correctly.

Current Behavior

Possible Solution

Context

My spec won't validate.

[hkosova]

Here's the correct version:

      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tower'
              examples:
                example-one:
                  value:
                    Status: Success
                    Data: Something

Response examples are defined under the media type, and the value keyword is used if the example value is specified inline (as opposed to externalValue).

[johndunderhill]

This validates (no parser error), but it does not show the example in the generated documentation.

[hkosova]

UI does not render media type examples yet - see #3437.

As a workaround, you can add example to your Tower schema:

components:
  schemas:
    Tower:
      type: object
      properties:
        ...
      example:
         Status: Success
         Data: Something

or

components:
  schemas:
    Tower:
      type: object
      properties:
        Status: 
          type: string
          enum: [Success, Failure]
          example: Success
        Data:
          type: string
          example: Something

[johndunderhill]

That works for me, thank you.