OpenAPI Examples are not respected in generated documentation

[mahirk]

Describe the bug
Postman API to Collection generation does not support examples in the objects. The strategies are described here: https://swagger.io/docs/specification/adding-examples/

To Reproduce
Steps to reproduce the behavior:

1. Go to "Browse"
2. Click on "Create new API" with "Open API 3.0"
3. Enter test names and open "Define"
4. A sample schema should be present. Replace the schema with

openapi: 3.0.2
info:
  title: My API
  version: 0.0.0
paths:
  '/users/{someOtherString}':
    post:
      operationId: CreateUser
      parameters:
        - name: someOtherString
          in: path
          description: property-two-examples description
          required: true
          schema:
            type: string
          examples:
            property-example-one:
              value: stringOne
            property-example-two:
              value: stringTwo
        - name: someString
          in: header
          description: Header for XYZ ABC Purposes
          required: true
          schema:
            type: string
          examples:
            property-example-one:
              value: VALUE X
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
        required: true
      responses:
        '201':
          description: 201 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateUserResponse'
components:
  schemas:
    CreateUserRequest:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
      required:
        - firstName
        - lastName
    CreateUserResponse:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        role:
          type: string
      required:
        - firstName
        - lastName
        - role

5. Save
6. Click on "Develop"
7. Create Documentation
8. Open documentation

Expected behavior
The examples request and response should use the example values provided in the specification.

Screenshots

App information (please complete the following information):
App Type: Chrome App
Postman Version: Latest on browser
OS: [e.g. macOS Mojave 10.14.6]

[abhinaba-ghosh]

Hi, @mahirk Thanks for highlighting this behavior. I suppose you want to generate the request body as per the specified schema. There are a few steps and updations I followed to get the desired outcome.

• Describe the example in the target schema, like:

schemas:
    CreateUserRequest:
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
      required:
        - firstName
        - lastName
      example:
        firstName: 'mickey'
        lastName: 'mouse'

• Select Example at the time of Creating Documentation for Request/Response parameter generation.

• Open the Documentation

We will be happy if this resolves your issue. Feel free to raise concerns otherwise.

[mahirk]

Hey @abhinaba-ghosh
Thank you for the details!
I did try that for the schema. However, I believe that is only one way of defining an example per the OpenAPI documentation. The YAML provided above has the following snippet:

parameters:
        - name: someOtherString
          in: path
          description: property-two-examples description
          required: true
          schema:
            type: string
          examples:
            property-example-one:
              value: stringOne
            property-example-two:
              value: stringTwo
        - name: someString
          in: header
          description: Header for XYZ ABC Purposes
          required: true
          schema:
            type: string
          examples:
            property-example-one:
              value: VALUE X

This is a valid mechanism for defining an example as well per the OpenAPI Documentation:
Swagger OpenAPI 3.0: https://swagger.io/docs/specification/adding-examples/
OpenAPI Docs: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#example-object-examples

Would there be a way to access those example properties to match the full spec? Is there something incorrect with the above openAPI spec? I believe it has been validated correctly as well.

[kevinswiber]

This is a complicated part of the spec, for sure. This will also need consideration when we move to support OAS 3.1.x. See discussion here: OAI/OpenAPI-Specification#2336 (comment)

[mahirk]

Hey @vvs11 / @abhinaba-ghosh was just wondering if there was any update here?

[mahirk]

@vvs11 / @abhinaba-ghosh Checking in :)

[vvs11]

@mahirk No updates yet. Will get back to you on this as soon as there's an update

[philsturgeon]

Heads up, examples in OpenAPI are bonkers and there's a lot of similar but different approaches. https://phil.tech/2020/openapi-examples/