[Feature] Specification extensions support for Components Object

[karolkania]

As specified in OpenAPI Specification / Components Object - This object MAY be extended with Specification Extensions

I'm having issues with those Specification Extensions, it's always best to use an example to present what is wrong - I have two files and I'm trying to create a bundle using the main file as a root document.

Main OAS3 file (main.openapi.yml):

openapi: 3.0.2
servers:
  - url: 'http://localhost'
    description: server
info:
  version: 1.0.0
  title: Example API
  contact:
    email: a@a.com
  description: Example

tags:
  - name: sample

paths:
  '/sample':
    get:
      operationId: getSample
      summary: Sample
      description: Sample
      tags:
        - sample
      responses:
        '200':
          $ref: './components.openapi.yml#/components/responses/Default200Response'
      x-some:
        $ref: './components.openapi.yml#/components/x-some-ref/whatever'

Components / Responses OAS3 file (components.openapi.yml):

openapi: 3.0.2
servers:
  - url: 'http://localhost'
    description: server
info:
  version: 0.0.1
  title: Components fragment
  contact:
    email: a@a.com
  description: Components fragment

tags:
  - name: specExt

paths: {}

components:
  responses:
    Default200Response:
      description: Sample
  x-some-ref:
    whatever:
      key: value

When I'm creating a bundle with:

openapi bundle --output bundled.openapi.yml --ext yml main.openapi.yml

it parses perfectly the OAS3 fixed fields like components/responses references but fails parsing specification extensions (x-some-ref) references - it is just copied as-is.

The output file (bundled.openapi.yml):

openapi: 3.0.2
servers:
  - url: 'http://localhost'
    description: server
info:
  version: 1.0.0
  title: Example API
  contact:
    email: a@a.com
  description: Example
tags:
  - name: sample
paths:
  /sample:
    get:
      operationId: getSample
      summary: Sample
      description: Sample
      tags:
        - sample
      responses:
        '200':
          $ref: '#/components/responses/Default200Response'
      x-some:
        $ref: './components.openapi.yml#/components/x-some-ref/whatever'
components:
  responses:
    Default200Response:
      description: Sample

First of all, as specified in the OAS3 specs:

The extensions may or may not be supported by the available tooling

So these are optional, but It'd be extremely nice to have it parsed and supported.

Not an issue, more like a feature request.

[adamaltman]

I'm revisiting this old issue. I think one issue is this implies there is a components object with x-some-ref which doesn't seem like a valid property of components.

        $ref: './components.openapi.yml#/components/x-some-ref/whatever'

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#componentsObject

But I reviewed it again, and it is indeed a specification extension (starts with x- so it is legal). Seems like we should go ahead and resolve it and place it into components.