Convert OpenAPI3 examples to postman examples

Ask the Experts and Postman Tips
, ,
1

How can i convert OpenAPI examples to Postman Collection examples?

In OpenAPI 3, we can define different named examples for parameters, request bodies and responses, for instance

"/test-resources/{TYPE}": {
            "post": {
                "tags": [
                    "TestResource"
                ],
                "operationId": "create_test_resource",
                "summary": "Creates a test resource of type",
                "parameters": [
                    {
                        "name": "TYPE",
                        "in": "path",
                        "description": "Resource type",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "examples": {
                            "Success": {
                                "value": "CorrectType"
                            },
                            "Incorrect": {
                                "value": "InvalidType"
                            }
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "element_one": {
                                        "type": "string",
                                        "nullable": false
                                    },
                                    "element_two": {
                                        "type": "number",
                                        "nullable": false
                                    }
                                }
                            },
                            "examples": {
                                "Success": {
                                    "value": {
                                        "element_one": "yes",
                                        "element_two": 20
                                    }
                                },
                                "Incorrect": {
                                    "value": {
                                        "element_one": "yes"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "element_one": {
                                            "type": "string",
                                            "nullable": false
                                        },
                                        "element_two": {
                                            "type": "number",
                                            "nullable": false
                                        },
                                        "type": {
                                            "type": "string",
                                            "nullable": false
                                        }
                                    }
                                },
                                "examples": {
                                    "Success": {
                                        "value": {
                                            "element_one": "yes",
                                            "element_two": 20,
                                            "type": "CorrectType"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Input error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "error_code": {
                                            "type": "string",
                                            "nullable": false
                                        },
                                        "error_message": {
                                            "type": "string",
                                            "nullable": false
                                        }
                                    }
                                },
                                "examples": {
                                    "Incorrect": {
                                        "value": {
                                            "error_code": "400",
                                            "error_message": "Invalid Request"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }

In this case, it looks like when I generate a definition, I will get two examples (“Success” and “Incorrect”), with the request and the response defined with that name, but no, I’m only getting the examples based on the response codes (named with the description of each response) and the values are the first example defined.

image
image799Ă—514 27.8 KB

I want to know if it’s possible to define the postman examples from the openapi definition, it’ll be nice because the mock generation would be a lot faster working only on the oas definition.

1 Like
2

Hey @joint-operations-ca1 !

Not quite sure if I’m following, but this should work if you edit “Parameter Generation” to use “Example” instead of “Schema” while importing the OpenAPI file

Example: https://beta-sdk.photoroom.com/openapi

image
image832Ă—567 46.1 KB

image
image2463Ă—598 81.9 KB

3

Thanks for your reply.

In the example you provided (Photoroom API), they don’t use named examples, they just put a single example for every field and/or a default value.

image

Hence, the parameters, body and response values will be the same in all example requests when generating a collection.

What I want to do is generate example scenarios using named examples in OpenApi, in such a way that in a case like this

{
    "requestBody": {
        "content": {
            "application/json": {
                "schema": {
                    "type": "object",
                    "properties": {
                        "element_one": {
                            "type": "string",
                            "nullable": false
                        },
                        "element_two": {
                            "type": "number",
                            "nullable": false
                        }
                    }
                },
                "examples": {
                    "Success": { // Success Scenario
                        "value": {
                            "element_one": "yes",
                            "element_two": 20
                        }
                    },
                    "Incorrect": {  // Incorrect scenario
                        "value": {
                            "element_one": "yes"
                        }
                    }
                }
            }
        }
    }
}

It will generate two examples in collection for this path.

In the Success scenario, the request body should be

{
  "element_one": "yes",
  "element_two": 20
}

but in the Incorrect scenario, the request body should be

{
"element_one": "yes"
}

And applying the same logic for parameters and responses.

1 Like
4

This still does not work. Request body examples are not generated. this is a huge issue with using postman for api documentation.

5

@jonkwine, looking at the API Definition you provided, it seems you are using inline Body schema declaration. I was able to get body examples generated in Postman by using a reference to a request object schema in components section (it’s also a best practice :slightly_smiling_face:).
Adding Examples | Swagger Docs

That said, Postman will attempt generate an exhaustive list of possible request/response combinations.
Assuming Request has two examples A & B, and returns Status Codes 200 and 400, where status code 200 has two examples 1 & 2. This the expected generated examples combination:

  • Example A → Status 200 example 1
  • Example A → Status 200 example 2
  • Example A → Status 400 example
  • Example B → Status 200 example 1
  • Example B → Status 200 example 2
  • Example B → Status 400 example

I hope this helps

1 Like
6

Thanks. Seems like it is an issue only on 1 of my path > request > example

1 Like
7

In my case, when a pattern is specified in the requestBody of openapi.yaml, it was set as the example in Postman.
When I removed the pattern, the example in openapi.yaml was set as the example in Postman.
This is a troublesome specification.
Is it possible to have the example in openapi.yaml set as the example in Postman even when a pattern is specified?