Feature: Add JSON language option to Documentation viewer

[djbf]

App Details:

Postman for Mac
Version 5.1.3
OS X 16.7.0 / x64

Issue Report:

My team would find the documentation generated from our Postman Collections more useful if Sample Requests were viewable as JSON.

This is currently possible with Apiary, Restlet, etc. and its inclusion would eliminate our need for a separate documentation solution.

[sdnts]

@djbf The dropdown you're opening is generating code for the request you're currently on based on the language you choose. Since JSON isn't a programming language, it wouldn't quite fit there.

Are you looking for JSON representation of your request?

[djbf]

Curl isn't a programming language, yet it's there. Python Requests is a library, not a language. What about the urllib2 people? :) I see that dropdown as formatting examples, not really specific to core programming languages.

I see the BODY request in the middle pane, but it'd be a nice enhancement if the request and response could be viewed in line with one another, styled in the same manner, and with real values and not {{}} variables as entered in the Postman client.

For example, if we stick with the "sample" nomenclature, it'd be useful to have the current BODY section in the middle column, where the more expository text lives, be something like:

{
    "user_id": integer,
    "name": string,
    "type_id": string,
    "description": string
}

That's more descriptive, obvious, and helpful than this:

{
    "user_id": {{user_id}},
    "name": {{$guid}},
    "type_id":"{{type_id}}",
    "description": "{{description}}"
}

In the darker "code" section, the styling developers naturally gravitate towards, having an obvious relationship between the Sample Request and Sample Response would help the cognitive aspects of documentation. For example:

Sample Request:

{
    "user_id": 1,
    "name": "tmp_2b4253c5bc408421891f45b07d074549",
    "type_id": "1",
    "description": "blahblahblah"
}

Sample Response:

{
  "result": {
    "id": "10",
    "name": "tmp_2b4253c5bc408421891f45b07d074549",
    "description": "blahblahblah",
    "profile_image": null,
    "created_date": "2017-08-31 18:21:00.123456",
    "user_id": 1,
    "visibility": "public"
  }

Maybe being able to save a request as an example, similar to how saving responses is implemented from the docs perspective could help here.

[sdnts]

@djbf Currently, example responses do not show up in the Documenter, but if I understand correctly, showing that should resolve your issue as well correct?

This is in the works.

[djbf]

I'm a little confused... Example responses I save from within the Postman client are indeed displayed in the documentation and are very useful.

It's that urls and sample bodies/requests that contain variables do not good API documentation make. If I can control the sample responses that are displayed, it seems I should have some control over how sample requests and/or request bodies are presented, which are ostensibly more important than responses.

Hopefully the screenshot elaborates on my suggestions a bit more because I sincerely appreciate you addressing my feedback!

[sdnts]

@djbf Ah, understood. In the mean time, you can edit your examples from within the app to remove any information you do not want to be public. We'll look into this :)

[djbf]

Also worth noting for the benefit of others reading this is that in the Documenter, shared environments can be selected in a dropdown which will populate the BODY variables displayed.

Perhaps an additional consideration when strategizing on any sort of implementation would be the ability to set a default environment, rather than "No Environment" being the default on page load or refresh.

[sdnts]

@djbf When you publish your documentation, you can attach an environment to it in that step. When you do that, that environment becomes the default in the dropdown .