OAS 3.0: Support for media type examples (aka request/response body examples)

Version: ft/oas3 branch, as of commit a1ce0e7

OpenAPI 3.0 has requestBody.content.<media-type>.example(s) and responses.<code>.content.<media-type>.example(s). UI currently does not use these examples, but it would be great if it did. They are supposed to override schema-level examples if any.

Spec:

openapi: 3.0.0
info:
  version: 0.0.0
  title: test

paths:
  /something:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
            example:
              message: request body example
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              example:
                message: response body example

components:
  schemas:
    Message:
      type: object
      properties:
        message:
          type: string
          example: property-level example

[ghost]

The docs state that this functionality exists: https://swagger.io/docs/specification/adding-examples/

@shockey Would it be possible to write in the documentation that this functionality is currently defective? It was pretty frustrating sitting their for an hour trying to get it working only to eventually find this issue.

[niklasnorin]

This issue is incredibly annoying. We’re using the same Schema object in request and response, except that there are some subtle differences in how you should use it. It would have been perfect to be able to distinguish this with separate examples for the same schema object.

Also showing multiple examples in requests will be awesome.

Can’t wait for this to be fixed!