[Feature] Specification extensions support for Components Object
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 1.5k
- Forks
- 228
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 48
Description
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the bundle with main.openapi.yml, components.openapi.yml, and openapi bundle --output bundled.openapi.yml --ext yml main.openapi.yml. Compare the resolved components/responses reference with the unchanged x-some reference; done means specification-extension references are bundled consistently with fixed fields.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, typescript
- Domain
- api, cli
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100