Skip to content

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

@SandroG

Description

@SandroG

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"

Metadata

Metadata

Assignees

No one assigned

    Labels

    re-use: ref-everywhereRequests to support referencing in more / all places

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions