Examples are imported incorrectly from OpenAPI definition

[ash007-postman]

Describe the bug
Examples are imported incorrectly from OpenAPI definition and the bug also appears while generating collection in APIs in Postman.

To Reproduce
Steps to reproduce the behavior:'

1. Click on Create API
2. Click on Add Schema > Create new
3. click on create example response: Define the example

4. Error: Example response is not displayed as defined

Expected behavior
To be able to receive the example response as defined for the collection.

Screenshots
If applicable, add screenshots to help explain your problem.

Additional context-
Removed postfix /value from OpenAPI definition described in the example, no result. Using /value at the end of the reference link was the only way to get example visible in rendered HTML of Swagger UI`.

App information (please complete the following information):

• App Type- Native App
• Postman Version -7.1.0
• OS: [Windows]

[abhijitkane]

@ash007-postman More details, please. Can you share snippets of the OpenAPI spec that should be imported in a different way?

[kholmukhamedovme]

@abhijitkane here you are.

openapi: 3.0.2

info:
  title: API
  version: "1.0"

paths:

  /core/status:

    get:
      summary: Get system status
      operationId: getSystemStatus
      responses:
        '200':
          description: "System status successfully retrieved case."
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/SystemStatusModel'
              example:
                $ref: '#/components/examples/GetSystemStatusResponseExample/value'

components:
  schemas:
    SystemStatusModel:
      type: object
      required:
        - isDayClosed
      properties:
        version:
          description: "Current version of API build."
          type: string
        uptime:
          description: "Uptime of service in minutes."
          type: integer
        isDayClosed:
          description: "End of the day flag."
          type: boolean
      example: {
        "version": "0.4.0",
        "uptime": 2837,
        "isDayClosed": true
      }
  examples:
    GetSystemStatusResponseExample:
      summary: Get system status response example
      description: "This is an example of get system status operation response in case of system status successfully retrieved. Send with HTTP status code 200 OK."
      value: |-
        {
          "version": "0.4.0",
          "uptime": 2837,
          "isDayClosed": true
        }

Just import it in Postman, then go to the request example and you'll get:

{
 "$ref": "#/components/examples/GetSystemStatusResponseExample/value"
}

[abhijitkane]

@kholmukhamedovme This PR (https://github.com/postmanlabs/openapi-to-postman/pull/62/files) should fix the problem. We'll include this in the next release of Postman. Thanks for reporting this.

[kholmukhamedovme]

Hey, @abhijitkane!

I was wrong. I have been writing an invalid OpenAPI definition for examples as SmartBear support says:

Hi Farrukh,

The code in your specification is incorrect, so the example is not rendered in the UI Doc's Response body properly. I have attached a screenshot demonstrating the correct usage of examples in a response body description. How does it work with your mocking integration?

Here are the details of how to reuse examples in OAS 3.0 specifications:
https://swagger.io/docs/specification/adding-examples/

BTW, UI rendering of multiple "examples" is not supported yet, this is tracked in SWOS-27. It's for internal usage, but you can get updates of the issue providing us with this number. At that, the mock supports "examples".

Please let me know if you have any questions.

Regards,
Julia Kolosova
SmartBear Customer Care

But although, if you look at OpenAPI specification there is a Media Type Object which may contain example for single example and examples for multiple examples. I used the first one. And if you use it in Swagger UI, it will not display an example w/o /value postfix in reference link. So I used that invalid postfix.

[kholmukhamedovme]

Anyways, Postman doesn't import examples properly even with valid OpenAPI definition from SmartBear's point of view.

So leave PR merged or add also support for importing multiple examples.

[kholmukhamedovme]

I was wrong again.

If I use single example object:

• I see my example
• But mock service doesn’t work

If I use multiple examples object:

• I don’t see my example
• But mock service works

If I try to use both of them:

• Validator says that API specification is invalid and can’t be rendered

So just leave as is. I mean add this PR to release.

[reinouts]

Might be the same issue: from a OpenAPI spec like this:

paths:
  "/services/deployments":
    post:
      tags:
      - "Register"
      summary: ""
      description: ""
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "ApplicationInstance"
        required: true
        schema:
          $ref: "#/definitions/ApplicationInstance"
...
definitions:
  ApplicationInstance:
    type: "object"
    properties:
      InstanceName: 
        type: "string"
        example: "Test"
      InstanceId: 
        type: "string"
        example: "bf40055d-8d9c-45db-a9e5-ddb30e0d0846"
      InstanceURL: 
        type: "string"
        example: "https://instance.url/"
...

The POST body generated by Postman is just ApplicationInstance.

[abhijitkane]

@kholmukhamedovme @reinouts Can you try out the latest version of Postman Canary (https://getpostman.com/canary), and see if that fixes this? We've rolled out a bunch of improvements around the OpenAPI import flow.

[kholmukhamedovme]

@abhijitkane yes. I tried and here what we've got:

It generates invalid JSON :(

[reinouts]

@abhijitkane Unfortunately the behavior is still the same. The generated request body is whatever is in the body descriptionelement, not what is in the actual referred schema definition.

[abhijitkane]

@reinouts This seems to be a different issue - the JSON request body from the parameters property isn't handled. Can you file a new issue on https://github.com/postmanlabs/openapi-to-postman/issues, with a complete spec that's causing this?

[kholmukhamedovme]

Thank you very much! This issue has been fixed in the latest v7.1.1-canary08.

[abhijitkane]

@kholmukhamedovme This is fixed in prod as well.

[ambition-consulting]

Still broken for all kinds of multiple examples: https://swagger.io/docs/specification/adding-examples/

[VShingala]

@ambition-consulting Issue is fixed but not working for example that you gave due to a different issue, I have created issue that is happening here. We will add any progress on the same over that thread.

[ambition-consulting]

Okay, thank you. I'm looking forward to using the same data for testing and Swagger execution. :-) Vishal Shingala <[email protected]> schrieb am Di., 2. März 2021, 12:33:

…

@ambition-consulting <https://github.com/ambition-consulting> Issue is fixed but not working for example that you gave due to a different issue, I have created issue that is happening here <postmanlabs/openapi-to-postman#338>. We will add any progress on the same over that thread. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#6538 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABAF3XSKQJPTYB6YONAECZ3TBTEJ7ANCNFSM4HNVB7MA> .

[mryhmln]

This doesn't work for me either. Is it even possible to get an example from an API spec into in a collection when you create the collection from the spec? I have tried many different ways of doing it: including it as a reference, including it inline. Nothing seems to work.

[VShingala]

@mryhmln To use examples from your API definition in collection, you need to provide certain options while generating the collection or importing definition.

You can select options via View Import Setting button at bottom left of modal. Choose Example as value for option named Parameter generation. This will make sure that examples mentioned in API definition are used whenever available.