Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow the use of $ref and json pointer in tags #2905

Closed
SandroG opened this issue Mar 28, 2022 · 1 comment
Closed

Allow the use of $ref and json pointer in tags #2905

SandroG opened this issue Mar 28, 2022 · 1 comment
Labels
re-use: ref-everywhere Requests to support referencing in more / all places

Comments

@SandroG
Copy link

SandroG commented Mar 28, 2022

In the main openapi.yaml file I need to do something like:

tags:
  - $ref: "./customers.yaml#/tags/0"

This should be a valid JSON pointer if I'm not mistaken.
Unfortunately, AFAIK the OpenAPI spec does not permit to use $ref in tags.

Reason

I have a large specification, which I need to break down in different files. I use an approach where each file is like a sub-specification that lists all endpoints regarding the same subject and then I include these endpoints in the main openapi file.
The documentation of a tag is in the same file as the endpoint that uses it.

I'm not able to reuse that tag declaration in the main file, so I'm not able to include the description of the tag.

Example

For example, I have a separate file for customer's endpoints
customers.yaml

info:
...
tags:
  - name: Customer
    description: APIs to manage customers. A customer is a representation of ...
  
paths:
  /customers/{id}/:
    parameters:
      - name: id
        . . .
    get:
      . . .
  /customers/:
    . . .

I need to do this:
openapi.yaml

info:
...
tags:
  - $ref: "./customers.yaml#/tags/0"
  
paths:
  /customers/{id}/:
    $ref: "./customers.yaml#/paths/~customers~1{id}~1"
  /customers/:
    $ref: "./customers.yaml#/paths/~customers~1"
@handrews handrews added $ref re-use: ref-everywhere Requests to support referencing in more / all places and removed $ref labels Jan 28, 2024
@handrews handrews changed the title Allow the use of json pointer in tags Allow the use of $ref and json pointer in tags May 24, 2024
@handrews
Copy link
Member

Consolidating under #3853 and closing

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
re-use: ref-everywhere Requests to support referencing in more / all places
Projects
None yet
Development

No branches or pull requests

2 participants