OpenAPITools / OpenAPITools/openapi-generator

[REQ] OAS3 Tag/template to define external-components URL

Open
#3,401 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Enhancement: Feature
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.