-
Notifications
You must be signed in to change notification settings - Fork 9.2k
Closed
Labels
re-use: ref-everywhereRequests to support referencing in more / all placesRequests to support referencing in more / all places
Description
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"kisidav and lornajane
Metadata
Metadata
Assignees
Labels
re-use: ref-everywhereRequests to support referencing in more / all placesRequests to support referencing in more / all places