Skip to content

OpenAPI v3.1: Support for $ref siblings #2918

Open
@lcawl

Description

@lcawl

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"
          },

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions