Allow description to be an object as well as a string

[darcyrush]

Our company uses OpenAPI for contract first development. In practice this means that not only Developers utilize OpenAPI contracts, but also DevOps and Security teams.

As such, each team uses the contract for different purposes. This often means we add different descriptions for each team.

However, since the description property value is string, to target each team, we need to use an agreed internal notation like [team] followed by information specific for that team. Adding multiple teams and descriptions within the description string value causes our descriptions to balloon in size and are incredibly difficult to read.

If descriptions could also be allowed to be objects (or worst case, array) we instead could use the team names as properties and value description targeted specifically to them.

Although this may seem like a very specific use case, I think it could allow much more generic use cases. For example, many APIs allow for dynamic payloads or requests. While these can sometimes be accurately described by OpenAPI itself (and JSON Schema), sometimes this is simply not possible, and additional context in the form of nested descriptions would help immensely.

One example I can think of would be the somewhat common use of URL parameter filtering using some variation of term[operator]=value. I believe there was discussion in other thread about the fact that no official support could be added to OpenAPI because there is no consistent implementation across languages and libraries. While not great, a description object with properties of the operators would give some flexibility in the description of each available operator.

Perhaps this (or a similar solution) could be considered for the next major version of the OpenAPI spec?

[handrews]

@darcyrush this would (as you mention) be too big for a minor release, and for the next major release, we're doing a very comprehensive re-think over in the OAI/sig-moonwalk (although please be aware that much of that info is out-of-date as we've taken a step back to analyze the tooling ecosystem and make sure we're really aligning with implementation needs).

In the meantime...

I notice you don't mention which Object or Objects are involved in this use case. Do they by chance support the externalDocs field as well? External Documentation can be in any format, which would allow you to structure data however you want.

Another option would be creating variations on your OpenAPI Description (OAD) using the recently-publish Overlay Specification.

[darcyrush]

@handrews Thank you for the prompt reply. So in our case, it was paths, so we could indeed use external-document-objects as a workaround, while giving a dummy URL I guess (or using the URL as the team name).

For now it is an acceptable workaround, so thank you for the suggestion.

[handrews]

@darcyrush great, I'm glad that helps!

I notice you are linking to Swagger's version of the specification. While the Swagger site has some really great supplemental documentation, their spec rendering is out-of-date. Please use the official spec site so that you can look at the 3.1.1 spec which has a lot more info than 3.1.0 (but no new requirements- everything in it is also valid for 3.1.0).

(PS we are working on improving the spec site layout)