OpenAPITools / OpenAPITools/openapi-generator
[REQ] OAS3 Tag/template to define external-components URL
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Hi there, I'm not sure if this question/feature-req applies here or not, but sure if it is implemented affects the generatior, so here I ask:
I find myself using the power of $ref to reference external components in my API definitions, which is great as allows component reuse. But I find myself with this kind of code in my API definitions, where the links to external components are very long and hard to read:
/foo/validate/{bar}:
post:
tags:
- Foo
summary: Validate Foo
operationId: validateFoo
parameters:
# path
- $ref: '#/components/parameters/bar'
requestBody:
$ref: '#/components/requestBodies/FooValidation'
responses:
'200':
$ref: '#/components/responses/FooValidation'
'400':
$ref: 'http://repos.my-organization.foo/artifactory/libs-release-local/foo/myproject/api/contract/apicomponents-errors/1.0/apicomponents-errors-1.0-api.yaml#/components/responses/BadRequest'
'401':
$ref: 'http://repos.my-organization.foo/artifactory/libs-release-local/foo/myproject/api/contract/apicomponents-errors/1.0/apicomponents-errors-1.0-api.yaml#/components/responses/Unauthorized'
'403':
$ref: 'http://repos.my-organization.foo/artifactory/libs-release-local/foo/myproject/api/contract/apicomponents-errors/1.0/apicomponents-errors-1.0-api.yaml#/components/responses/Forbidden'
'500':
$ref: 'http://repos.my-organization.foo/artifactory/libs-release-local/foo/myproject/api/contract/apicomponents-errors/1.0/apicomponents-errors-1.0-api.yaml#/components/responses/InternalServerError'
I would really like to know if is there any way to define the base-path of that URLs in some kind of variable or YAML tag, so I could lead to $refs of this form:
$ref: '{apicomponents-errors}#/components/schemas/Something'
where I could define apicomponents-errors: http://... just once.
This is not only for better readability, but to allow update the versions all-in-once, as you can see from this example that the referenced components are versioned by its URL.
I have no idea if such kind of feature exists or can be implemented in OAS 3.
P.S. This does not only applies to schemas, but any kind of ref.
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
Start by checking the OpenAPI 3 specification and the repository's handling of external $ref values; the issue names no files, tests, or entry points. Use the YAML example to determine whether a reusable base URL can be defined for external components, and document the supported approach or the implementation scope required.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100