FR: Ability to have Required or Optional request parameters

[jordan-wright]

1. Postman Version: 4.10.3 (4.10.3)
2. App (Chrome app or Mac app): Mac app
3. OS details: 10.12.3 (16D32)
4. Is the Interceptor on and enabled in the app: No
5. Did you encounter this recently, or has this bug always been there: Always been there
6. Expected behaviour: Having the ability to mark a request parameter as required or optional.

This is similar to #1155, but I thought it'd be worth expanding on the idea.

Many APIs have request parameters that are optional or required. It would be very beneficial to be able to mark these in such a way that the request won't be sent if the param is required and not provided.

Additionally, if a param is optional, is using a variable, and isn't provided, it could be removed.

Normally, I would handle these via the request.data object in a pre-request script, but unfortunately that object is read-only. This also makes it difficult to use variables since if an environment variable isn't provided the actual {{}} syntax is sent instead of a blank string unless I manually clear out the variable.

I'm still fairly new to Postman, so I could be missing something.

Let me know if you have any questions, and please keep up the great work on Postman!

[ewpeters]

I would love this as well

[poisa]

I would love to have this too. Discriminating between optional and required is a must when writing documentation.

[cosmini]

I'm surprised that this doesn't exists. How can I document optional variables or params other than creating an example endpoint for each one of them and overloading my documentation.

[a85]

You can use parameter level descriptions to indicate whether they are required or optional in the docs. You can also use request level descriptions to document other metadata.

[cosmini]

@a85 This what I do at the moment and if I feel like something is too confusing I'm saving another example request with appropriate description.

I would be nice if they can provide an article or document to guide us on how to better use their app in such cases.

[a85]

Agreed. Working on making this better along with documentation and best practices. Will update the thread when we have something new. :)

[sahas-]

+1 for this ask, please. I've a swagger spec. Creating mock service in Postman, lack of optional vs required request parameters leads to incorrect representation of the spec.

[StephenOTT]

+1

[StephenOTT]

The biggest issue that is disabled params dont show up in the Documentation, and if you enable all of the params you have docs that look like complete junk.

At the very least, lets show the disabled params in the documentation

[gabma]

Same issue here, we have optional params that we would like to appear in the documentation but not have included by default in the "Example Request” or in the Url

[vendion]

The biggest issue that is disabled params dont show up in the Documentation, and if you enable all of the params you have docs that look like complete junk.

At the very least, lets show the disabled params in the documentation

I like this idea and might be an easy way to denote a required param and an optional one. If a param is "disabled" it doesn't show in the example query string but would be in the param table of the generated documentation.

[merihsakarya]

+1

[mzniko]

+1

[dusty]

I just noticed another reason for having optional/required. If you export your postman collection and then import it into something openapi-ish, such as apimatic, it marks all the params as required.

[nikolaip]

+1

[owaisafaq]

Would be good to have this.

[hussonkevin]

+1

[bdavies]

+1

[kid1412621]

+10086

[torbjornlarssen]

+1

[majidalavizadeh]

+1 in 2019 :)

[flowdee]

+1

[c3nj1]

+1

[NikitaBarford]

+1

[MattStrybis]

+1

[w3b5urf3r]

+1

[nonsocode]

😕Does the postman team not think that this is important? It's been nearly 2 years since this issue was opened

[douglasduartetb]

+1

[raym0nd93]

+1

[aaronn]

+1

[RomuloVHSYS]

+1

[RomuloVHSYS]

@a85 @vkaegis do you guys have any news?

[RomuloVHSYS]

Version 7.0.7 April 26, 2019

More than TWO YEARS, we still have the same issue.

[a85]

Everyone, this is part of a much larger initiative but we are introducing the ability to define APIs in Postman using schemas. You will be able to document schemas for both requests and responses using whatever format you typically use. Postman will then take this as another input in generating docs, building mocks, or adding tests. It looks like this:

Eventually, this will also allow you to link multiple collections to the same schema and reference individual schemas for each request inside a collection. We feel this is a much more scalable way to handle reusability issues. Essentially this is a kind of request inheritance but instead of doing this from one request in another collection, you'll be doing this through a schema. We will start with OpenAPI and RAML in the beginning but will be extending this to GraphQL and the Collections format itself.

We'd love your feedback!

[sheerlox]

@a85 hey, even if I document properly (in terms of required fields) my JSON requestBody with OpenAPI 3.0, it's still not displaying on my documentation. Can we have an update on this, btw I am willing to make changes to converters or help in any way possible to see this feature ASAP. I actually use Postman to document the API of the company I work in and it's such a impediment not to be able to specify which fields are mandatory. Thanks in advance.

I basically agree with what @RomuloVHSYS said in #3117:

If the idea is to use the schemas for generating docs (which is working well), so docs should accept all properties that those schemas are using, like type, format, required and others.

[RomuloVHSYS]

Ayn news?

My enterprise is about to release some new products and will only purchase the postman enterprise if the documentation can show the request properties without append then to the url, it's so simple..

Required/Optional it's just a way to do that

[sheerlox]

So basically I made a script for my company that populates some datas in the Postman collection. I'll try to make it available quickly, as I'm working to release a skeleton project for our API architecture (AWS Lambda + API Gateway + OpenAPI 3.0 + Postman). I'm working on the Docker for local development as it is a priority for now, and I'll be updating you with the skeleton here ASAP.

The only solution I found for required fields right now is to insert them in the description like: "Required fields:\n- Field 1\n- Field 2\n- etc ...". It is clearly not optimal nor it makes the documentation professional, but I'm trusting you guys to make some GET params / POST body table with required column, which would be really clean.

Property	Type	Required
field1	string	true
field2	string[]	true
field3	number	false

This is only a quick example, supporting nested objects description would be really nice too !

[cameronwlewis]

+1

[rashmi-tondare]

+1

[sheerlox]

Please avoid "me too" or "+1" comments. Instead, use a thumbs up reaction on enhancement requests. Maintainers will often prioritize work based on the number of thumbs on an issue.

[DmitriyKashin]

Hi Postman! It's really bad that you don't have this feature. (And examples reordering, people asking for that from 2015).

The new API module is a good idea, but I can't use it, I don't know why should I use it.

Params Examples, required / optional params, response format, enum, custom schemas, and other Openapi specs are just ignored by the postman, and not showing in documentation or requests. All the things, that I need to be transferred from Openapi spec to beautiful API documentation just missed.

First of all, I need good documentation for my API. I expect there to be an example of params, their types or patterns, response format, but instead, I need to write all these things manually with Markdown in Param description, or request description, or folder description, or collection description. I can't show original API link without tons of params, because if I disable them, they will not be documented. It's just impossible! You are showing 100 params in the link, or showing nothing and writing markdown table for all the params, and it has no binds with the request.

Look at your own API best example Imgur. They need to write all the things manually. https://apidocs.imgur.com/?version=latest#a94d108b-d6e3-4e68-9521-47ea79501c85

As a result, I open it with Postman and see NOTHING! Because of all the things described in Markdown.

Is it ok, that I get absolutely empty Postman-request set of Imgur or Travefy collections when I open it? I can't see response formats, params, their types, and my "source of truth" is Markdowns in descriptions.

Postman is a great project, but please, add some absolutely basic stuff instead of new beta features to your project and it will be perfect.

[Zavierazo]

+1

[YitziG]

Glad I came across this page. I assumed I was missing something.

[Edgame2]

Big +1 . Would be super helpful.

[dev-saima]

+1

[triplea-dev]

Nothing yet? Forced to use schemas just for something simple but as important as optional/required parameters in JSON data?

[rainabba]

Yes, we are still waiting ;)

[sanudatta11]

This is implemented or Still OPEN from 2017?

[akshaybhalotia]

Does adding a +1 help here?

[Raja-Simha]

Hey everyone, You can now generate documentation from OAS definition in Postman with all the schema info defined in your definition, including required or optional info for params. You can follow the steps here to try it out.

This is only the first step and we have further improvements planned. Request everyone to give the feature a spin and share your thoughts and feedback. Please highlight and explain which of your use cases are not solved and we will try to address them.