Postman response schema in API Documentation

Question

I created a collection in Postman that should work as my API documentation. I know, that for every endpoint I can save example responses, that will be included in the documentation.

Now I would like to include a response schema as well, so that people see a general definition of the data types and structure of the response. In OpenApi this is possible within the "response" block like this:

    "responses": {
      "200": {
        "description": "200 response",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/User"
            }
          }
        }
      }
    }

...
 
"components": {
  "schemas": {
    "User": {
      "title": "User Schema",
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  }
}

Is there a similar way to do this in Postman as well? I searched the documentation for quite some time but could not find anything useful except for one line here that sounds like it should be possible:

Each collection / request listing indicates the method, required authorization type, URL, description, headers, request and response structures, and examples.

This isn't possible for OpenAPI schemas. That extract from docs relates to what is automatically generated in the Collection Documentation. You could add that within the description but not in the same way as you would see the request/response examples. — Danny Dainton

PDHide PDHide · Accepted Answer · 2021-06-24T13:27:44

Description supports markdown language you can use below content :

# Schema:

```
  "responses": {
      "200": {
        "description": "200 response",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/User"
            }
          }
        }
      }
    }

...
 
"components": {
  "schemas": {
    "User": {
      "title": "User Schema",
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  }
}
```

output:

Postman response schema in API Documentation

1 Answers