Forum Discussion

Bains's avatar
Bains
New Contributor
4 years ago

OAS3 Reference to external document schemas

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
 
  • Bains's avatar
    Bains
    4 years ago

    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'

     

  • Bains's avatar
    Bains
    New Contributor
    4 years ago

    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'