Offer a way to pre-set certain set of values to the input masks

[dothebart]

When documenting an API one may want to demonstrate certain sets of parameters to ease the users grasping of what are sensible values to achieve a certain thing with the API.

Right now the input masks will only offer a valid value that is accepted in order to the value definition as default ala:

"path": "string",

so while string may be an acceptable value for this API according to the API definition, its educational value isn't as high in telling the user which values bring the API to life in a sensible way.

If one would now be able to pre-set a set of parameters into the formulars one could i.e. have

• one set named temporary file setting path to /tmp/some-temporary-file.txt
• another set named User document setting pathto ~/Documents/some-document.txt

and thus teaching the user in a better way how to use the API above its fundamental definition.

Such sets of values could be read from another json structure similar to the swager route matching part:

'/this/route/foo'.post = [
{
  description: 'temporary file'
  body: { path: '/tmp/some-temporary-file.txt' }
  PathParameters: { ...}
  HeaderParameters: {...}
},
{
  description: 'User document'
  body: { path: '~/Documents/some-document.txt' }
  PathParameters: { ...}
  HeaderParameters: {...}
}

[shockey]

@dothebart, OpenAPI's Parameter Objects have example and examples fields that allow you to provide an initial input value to Swagger UI.

Further, if you're interested in having multiple OpenAPI files that mirror each other's structure and provide additional data about a definition, check out the several OpenAPI Overlays proposals (OAI/Overlay-Specification#39).

This sounds like what you're looking for, so I'm going to close this out. Feel free to reply if there's something I've missed!

[Simran-B]

The issue with examples is that it is bound to a single parameter, and there is apparently no way to define examples for a combination of parameters (or by extension requests).

You can have individual examples like this:

But not examples like { "attr1": "foo", "attr2": "bar"} to show that a particular set of parameter values does something meaningful.

This seems to be a spec issue in the first place however and is probably better discussed in e.g. this issue:
OAI/OpenAPI-Specification#2197