OAS3 Reference to external document schemas

API Swagger
, ,
1

Originally posted by Bains on February 11, 2021

Hi,

In my root api document (openapi.yaml) file, I am trying to make a reference ($ref) to a schema in an external document that is located in a directory under the root folder (/products/Products.yaml), but the reference keeps on failing (complaining).

I am using Open API Specification v3 (OAS3).

The details in my root api (openapi.yaml) for this issue is as follows:
paths: /product: post: description: Creates a new Product requestBody: required: true content: application/json: schema: $ref: ‘/products/Products.yaml#/components/schemas/CreateProduct’

I am able to navigate to the external document (/products/Products.yaml), but not the required schema (CreateProduct).

If you are able to assist me to identifying what is wrong with this API design this would be greatly appreciated.

Many thanks for any advice you can provide

Bains

2

Originally posted by Bains on February 11, 2021

I think i have worked it out.

My original reference was as follows:

$ref: ‘**/**products/Products.yaml#/components/schemas/CreateProduct’

What I did was modify it as follows:

 $ref: 'product/Products.yaml#/components/schemas/CreateProduct'

The culprit in this case was the leading slash (“/”) before ‘products/Products.yaml’.

Strangely i was also able to remove the leading slash before component and it worked also as follows:

 $ref: 'product/Products.yaml#components/schemas/CreateProduct'