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