Description
Priority: medium (unless there are other ways to get the descriptions propagated properly)
Effort: high
🚀 Feature Proposal
As a motivation for upgrading our OpenAPI generator from OAS 3.0 to OAS 3.1 (or later), it includes support for $ref siblings, per OAI/OpenAPI-Specification#2744
The generator would need to shift to outputting OAS 3.1 files and it would need to start including these sibling descriptions and summaries.
Motivation
We have some schema objects that are used in a lot of places (e.g. QueryContainer
in https://github.com/elastic/elasticsearch-specification/blob/main/specification/_types/query_dsl/abstractions.ts). The specifications that use that object have additional descriptions (e.g. the DatafeedConfig
query
has a unique description of its default behaviour). However, that information is currently missing from the OpenAPI 3.0 document since there's no way to override the shared QueryContainer
object's description.
Example
Here's an example of what is currently output for the datafeed_config in an OpenAPI v3.0 document (it looks the same for all the ~90 places that QueryContainer is referenced):
...
"ml._types:DatafeedConfig": {
"type": "object",
"properties": {
...
"query": {
"$ref": "#/components/schemas/_types.query_dsl:QueryContainer"
},
This is what I think we could accomplish instead in an OpenAPI 3.1 document:
"ml._types:DatafeedConfig": {
"type": "object",
"properties": {
...
"query": {
"description": "...By default, this property has the following value: `{"match_all": {"boost": 1}}`.",
"$ref": "#/components/schemas/_types.query_dsl:QueryContainer"
},