Add description of response in API Document

🙋 Help
1

Can I add description for the JSON response? Just like add description in the request parameters.

2

Hi Justin,

Not quite sure what you mean by “description for JSON response”. Do you mean a “Status Passed/Failed” message?

3

Hi Jonathanp,

For example, the response of API is as following:
{
“id”: “123”,
“name”: “Justin”
}

I want to show the description of id and name in document, like following:
id - user id
name - user’s real name

4

Hi @justin.liu, if I’m understanding the part of Postman functionality you’re working with correctly, looking at the docs it seems descriptions are only supported for data sent with a request (parameters etc) rather than response data:

https://learning.getpostman.com/docs/postman/collections/using_markdown_for_descriptions/#descriptions-for-request-attributes

I’m wondering if the descriptions are maybe not intended for your use case (API specifications and documentation are used for lots of different activities from integration and testing to user-facing learning material and so on).

If you could explain a bit more about what you’re trying to achieve with the response field description info in your project, perhaps someone will have a suggestion about how to implement it. :thinking:

5

So I know this question is eons old, but I’m wondering this myself.
I’m updating the documentation to my API and while I have editable areas for describing request body parameters and such, there’s nothing that I can recognize as being specific for describing the response body content.

While I can (and am) adding this information in the Description text of the method, I would have expected a section that would be marked up for this data.

6

I guess I can answer my own question.
Documentation does refer to this by suggesting to use an example as the template to show response data.

1 Like
7

This is a very needed ability in the Documentation. Sometimes a response is a “code” and it would be very important to be able to document what the various values mean (e.g. color=1 means red, color=2 means blue). Also, the data type is not always intuitive (i.e. 1 can be bool, int, string, etc.)

When documenting an API, the reader needs to understand the response, and the example template does not leave any room for that kind of description.