specify RESPONSE codes

[kabaluyot]

To document example response, we rely with the tags:

<! --RESPONSE -->
<! -- ENDRESPONSE -->

However, we may add specific responses, like 200 response, 401 response, 404 response.

Is it possible to add custom tags like:

[tiagopaes]

I think it is a great ideia!

[jozsefsallai]

I'm thinking of ways to implement this. Perhaps something like this could work:

<!-- RESPONSE 200 -->
<!-- ENDRESPONSE -->

<!-- RESPONSE 401 -->
<!-- ENDRESPONSE -->

and for backwards-compatibility:

<!-- RESPONSE -->
<!-- ENDRESPONSE -->

a regular expression could match either of these and capture both the example response and the status code

[jozsefsallai]

Good news, everyone! I've added support for this :) You can have as many responses as you want now and you can also specify the status code for each and every one of them!

The old <!-- RESPONSE --> and <!-- ENDRESPONSE --> method still works, it will just not display a status code at all.

The color of the header and the border will indicate the type of request:

• 1xx (info) - blue
• 2xx (success) - green
• 3xx (redirect) - brown
• 4xx (client error) - orange
• 5xx (server error) - red
• everything else - Insomnia purple

Here's what it looks like in action:

The description of the new section in the demo looks like this:

You can specify multiple example responses -- now with status codes! Instead of `<!-- RESPONSE -->` you can write `<!-- RESPONSE 200 -->`. You still have to close it using `<!-- ENDRESPONSE -->` though!

<!-- RESPONSE 200 -->
{
  "ok": true,
  "token": "123abc"
}
<!-- ENDRESPONSE -->

<!-- RESPONSE 400 -->
{
  "ok": false,
  "error": "Username or password not provided."
}
<!-- ENDRESPONSE -->

<!-- RESPONSE 401 -->
{
  "ok": false,
  "error": "Incorrect username and/or password."
}
<!-- ENDRESPONSE -->

Hope you guys find it useful and if you have any questions or suggestions, feel free to comment on this issue!

[shamscorner]

Great! I loved it and really appreciate that. But I have one recommendation here. For API, most of the requests are,

• GET - 200 (success)

• POST - 201 (created)

• PATCH - 200 (success)

• DELETE - 204 (no content)

• NOT FOUND - 404

• UNAUTHORIZED - 401

• FORBIDDEN - 403

• METHOD NOT ALLOWED - 405

• NOT ACCEPTABLE - 406

• BAD REQUEST - 400

• INTERNAL SERVER ERROR - 500

• BAD GATEWAY - 502

Did you get my point? I've just got 3 colors so far you know. Instead of getting the colors programmatically from the specified status code, you can make those variables (blue, green, brown, orange, red, etc) user-defined. Something like this,

<!-- RESPONSE 200 green-->
{
  "ok": true,
  "token": "123abc"
}
<!-- ENDRESPONSE -->

<!-- RESPONSE 400 orange -->
{
  "ok": false,
  "error": "Username or password not provided."
}
<!-- ENDRESPONSE -->

<!-- RESPONSE 500 red -->
{
  "ok": false,
  "error": "Incorrect username and/or password."
}
<!-- ENDRESPONSE -->

In that way, users will have more freedom. 🙂

[vinimello]

Hey guys, first of all thanks for the awesome documenter! I have a question, where do i put this tags with the response to show the block in my documentation? Is it in the json archive? In the docs in insomnia before exporting? I couldnt find where i put the tags, every place i tried it didnt work. Thanks for the help!

<!-- ENDRESPONSE -->
~~response~~
<!-- RESPONSE -->

[WinterCore]

Even though this is a bit late.

For whoever's wondering where to put the example responses.
You put them in the Docs tab of the request.
I honestly think this should be included in the README, because it was a little confusing.