Optional fields without example and default value should not appear in the example

[gnvk]

... or at least this should be an option.

Content & configuration

The PetStore has dozens of examples, e.g.:

 Category:
   type: "object"
   properties:
     id:
       type: "integer"
       format: "int64"
     name:
       type: "string"

From this the example in the UI is the following:

"category": {
  "id": 0,
  "name": "string"
}

Describe the solution you'd like

I would like to have an option not to display an optional field in the example, if it doesn't have an example and/or a default value, so the above example (since both the "id" and the "name" fields are not required and have no default/example value) should become an empty object:

"category": {
}

Describe alternatives you've considered

As a workaround we can use example='', default='' for a string, even though a missing parameter is not the same as a parameter with an empty string, and check for empty string on the server side.

Additional context

Context: we have an integration test that tests that the schema committed can be "tried out" without any modification. Having "string" values for optional fields that have no default values on purpose makes this impossible.

[shockey]

Thanks for the writeup, @GergelyNovak!

@webron - would appreciate your take on this request 👍

[webron]

@GergelyNovak do you use swagger-ui as a way to automate your integration tests?

Swagger-ui is intended first and foremost as a documentation tool, and being an interactive one, there's also the sandbox option. Since some users prefer looking at example option rather than the model one, as documentation goes, it's important to show a full example and not a partial one.

OAS3 provides support for multiple examples, so you can provide specific ones for different cases. It's true that we don't render those yet in swagger-ui, but it's still a good use case for what you're describing.

Having that as a configuration is ok, but in terms of priorities we have more urgent items to take care of right now. If you'd like to submit a PR for this functionality, we'd be happy to review it.