describing parameters is not complete enough

[loicginoux]

The way postman let us describe all parameters is not complete enough. Only having a "description" fields to explain every details related to a parameter seems not enough.

I miss fields like "optional/mandatory", "restricted values", a "default value" field, and a "type" field. So because of that I didn't see another way than to create a markdown table in the endpoint description, see how it is displayed below:

The problem with that solution is that for larger markdown table, the documentation displayed the markdown table truncated. See another example with more detailed parameters:

Is there a way to display the whole markdown table ? How can I document parameters properly ? Thank you

[Raja-Simha]

@loicginoux We are aware of the limitation around describing parameters. Unfortunately, the solution you have has a bug #7859 . We are actively working on fixing the bug. That should unblock you.

[Schwato]

Is "Later" still not somewhere nearby? Really could help with the Doc I am starting right now...

[makopov]

I'm curious about this as well, are there any plans to implement this?

[shashankawasthi88]

Hi,

I’m Shashank, a Product Manager at Postman. We’re exploring ideas for adding the ability to document request/response bodies, parameters, and more. This will allow you to provide additional details such as description, possible values, required/ optional, formats etc. for your JSON bodies and parameters as well.

Here is a recording of what the feature might look like. You can read more about the feature here.

This is in its early stages, and we’re seeking early adopters to try it out and provide feedback. If you’re interested, please reach out to me at [email protected] or schedule a call using this link.

Thank you!

[SeanDunford]

shashankawasthi88 The feature documentation that you provided is not available.

https://tw-1658-typed-collections.learning.postman-beta.com/docs/collections/typed-collections/

I would love to see optional parameters added to postman. Currently the Collection SDK and snippets provided do not do much to help generate api code for clients without these features. http://www.postmanlabs.com/postman-collection/

Have there been any updates?

[shashankawasthi88]

Hi @SeanDunford can you drop me an email to [email protected] and I'll enable the feature for you. Here is a detailed demo of what the solution looks like and here is the updated documentation.

[shashankawasthi88]

Hi All,

We are happy to announce the launch of Types in Collections for all users. This will give you the ability to describe types information for parameters - where you can provide information like default value, possible values, min-max value and a lot more!

Please do try out the feature and reach out to us if you have any feedback!