Redocly
Suggestion: "Optional" instead of "Required" on output.
OpenAPI has a list of "required" fields for each object and it makes sense to mark them as "Required" when describing input. However on output most fields are usually "Required". Perhaps it's wiser to mark those that aren't as "Optional" instead? In a way it would make it similar to "Nullable" tags. And once again, I'm talking about descriptions of output of APIs, inputs are fine with "Requried".
Let me give you an example. Let's say I have some API which returns an address, for that I would describe it as:
address1 (required) address2 city (required) company first_name (required) last_name (required) phone (required) country (required) province (required) zip (required)
And for the sake of example let's not discuss whether it's wise to omit fields on output or return empty strings instead. Let's say I decided to omit some of the fields in my API. Wouldn't it be nicer to display the same structure as:
address1 address2 (optional) city company (optional) first_name last_name phone country province zip
Maybe even make it smart and if most fields are "required", use "Optional" tag for those which aren't. If most fields are not "required", then use "Required" tag as usual. That simple logic will reduce visual clutter and lower cognitive load when reading docs. Or maybe add it as an option?
That's a feature request.
The described behavior should be optional, there are also APIs where most fields are optional, and in that case the current behavior is preferred.
The distinction that I would like to control is that on a POST operation, most listed properties are required, so it makes sense to only tag the ones not required as "optional". Conversely, on a PUT, where you're updating an existing, already identified object, most of the listed properties are optional so it makes more sense to tag the required ones as required.
Haven't seen a way to do this yet... still looking.
I realize this is a bit of an old issue, but I'd love to see support for an option to handle this. Our API typically assumes parameters are required, so marking the non-required ones as optional would be far more useful for us.
