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

[hkosova]

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

[gentlewind]

@webron , would you please share if this feature will be put on the release plan?

[hvt]

Would like to add that also supporting requestBody.content.<media-type>.examples and responses.<code>.content.<media-type>.examples would be of great value.

[kopinions]

any updates about this?

[john1452]

Hi is there any progress on this?

[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.

[shockey]

I believe @hkosova has the ability to correct those docs (I don't) 😄

[skyfore]

Errors

Schema error at paths['/map/model'].post
should NOT have additional properties
additionalProperty: requestBody
Jump to line 596

  '/map/model':
    post:
      requestBody:
        content:
          image/png:
            schema:
              type: string
              format: binary

Can I get help ? thks!

[hkosova]

@skyfore Make sure your spec is openapi: 3.0.0 and not swagger: '2.0'. The requestBody keyword is not supported in OpenAPI/Swagger 2.0. 2.0 uses form and body parameters instead.

In the future, please don't hijack threads with unrelated questions. Open a new issue instead, or ask your syntax questions in the Google Group, IRC or on Stack Overflow.

[skyfore]

@hkosova OK,Thanks for your reply 😃

[zeromodule]

I'm also waiting for the implementation of this functionality.
Today, the documentation on Swagger misinforms us.

[ghost]

A possible temporary (but also ugly) workaround to get a real example being shown could be to use directly a Schema Object instead of a Reference and provide the schema example. This would eventually generate a provided example instead of example with types.

[hkosova]

Adding a link to PR: #4092

[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!

[kzhou57]

Any update ?

[nesl247]

Glad to know I wasn't going crazy. Spent the last hour trying to figure out why my examples were not working.

[tlaukkan]

Its not really possible to do proper API documentation without this feature. Implementation would be highly appreciated.

[webron]

Supporting example right now is easier than supporting examples (see #2651). We'll work on adding support for the former next week, which should cover at least some of the use cases.

[b0ric]

Any news on the examples? This is a pretty vital part, can't believe it's open since more than a year.

[sasha-borodin]

@b0ric, in the same boat, and this is my understanding:

1. This issue was closed in Example #4730, which added support for "example".
2. Examples are not showing #2651 addresses "examples", but is still in the works.

[shockey]

@sasha-borodin, you're correct. We tracked support for example here, examples is still open over at #2651.