Parameters from JSON OpenAPI 3.0 schema not displaying in Postman API documentation

Ask the Experts and Postman Tips
, , , ,
1

Your question may already have an answer on the community forum. Please search for related topics, and then read through the guidelines before creating a new topic.

I’m using an OpenAPI 3.0 JSON schema for my API - I have checked my schema in https://editor.swagger.io/ and don’t see any issues, but am not seeing a section for parameters for any of my endpoints in my API documentation

schema:

 "/api/alerts": {
            "get": {
                "summary": "Get alerts",
                "description": "Returns the first 100 alerts by default - use the count parameter to view more results",
                "tags": [
                    "alerts"
                ],
                "parameters": [
                    {
                        "name": "count",
                        "in": "query",
                        "description": "set value to over 100 to view more than the first 100 results",
                        "schema": {"type": "integer", "default": 100},
                        "required": false
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "schema": {"type": "integer", "default": 0},
                        "required": false
                    },
                    {
                        "name": "sort",
                        "in": "query",
                        "schema": {"type": "string"},
                        "required": false
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {"type": "string"},
                        "required": false
                    }
                ],

SS from Swagger Editor with valid parameters section

image
image501×745 27.7 KB

SS of Postman documentation missing the parameters:

image
image781×641 25.8 KB

From viewing other public Postman API documentations, it seems like there should be a section that lists all the parameters for me - would appreciate help on figuring it out why it’s not displaying

Postman App version is Version 7.36.1 (7.36.1)

2

Hi @juliehive!

Thanks for posting in community :smiley:

I understand you are unable to see the params section in the documentation.

I tried the following and it worked for me.

  1. Create a new API without selecting a file (this auto-fill the schema in Define tab)
  2. Modified the schema based on your schema definition as shown at the end of this response.
  3. Params section are populated as below
    Screen Shot 2021-01-14 at 12.36.09 pm
    Screen Shot 2021-01-14 at 12.36.09 pm699×290 14.5 KB

Hope this helps :slightly_smiling_face:

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "test",
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "http://petstore.swagger.io/v1"
    }
  ],
  "paths": {
    "/asi/alearts": {
      "get": {
        "summary": "Details about a user",
        "operationId": "listUser",
        "tags": [
          "user"
        ],
        "parameters": [
          {
            "name": "count",
            "in": "query",
            "description": "ID of the user",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Details about a user",
            "headers": {
              "x-next": {
                "description": "A link to the next page of responses",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "default": {
            "description": "unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          },
          "tag": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "integer",
            "format": "int32"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}

I hope this helps!

3

Ok, I tried this and then experimented a bit and I think I figured out why it wasn’t working.

Even though I had the parameters in the schema, in the individual collection requests, the parameters were missing - it looks like if I manually add in the parameters and uncheck the optional ones, it will add it to the documentation (seen in screenshot)

It would be helpful if this was caught when doing schema validation, or maybe this is the reason that the app is showing that there is still issues when there doesn’t seem to be (related to one of my other posts), and it should be showing what the issues are?

image
image764×284 14.5 KB

Thank you for your help!

4

Hm, actually when I go to view my documentation, it is displaying the Request Params, but in the public documentation there is an empty section titled “Params” (ss below)

image

image

5

Hey @juliehive! Thanks for getting back :wave:

I found the same issue reported in our GitHub repo:

According to this thread, it seems that this behaviour is currently expected.
However, please do feel free to leave your comments in this GitHub issue to weigh in so that our product manager can use the feedback to prioritise and add to our roadmap :grinning:

6

Ah, okay thank you so much for this

1 Like