Start a new topic

Looking for example of multiple path files referenced each with multiple path items


I looked at beamup_api V3 multi-file example, which is what I was looking for.  However, each path file referenced has only one path item and if I include multiple path items, it is not working.  Lets say I have three set of APIs

  1. Users (/v1/users)
  2. Accounts (/v1/accounts)
  3. Orders (/v1/orders)

Parent file is main.yaml and each set of APIs reside in its own file, named as users_pathitems.yaml, accounts_pathitems.yaml, orders_pathitems.yaml

Each path items file has multiple path items.  And in main.yaml file, referencing those like below:


 $ref: "pathItems/users_pathitems.yaml#/paths/~1users"

however it is giving warnings and documentation doesn't generate properly.

Has anyone tried like above or are there any example available?


Hi Jay, 

I've attached a simple example. A few notes:

  • Each path reference needs its own key within the 

  • The 
    $ref property must be the only child property of the individual Path Item Object. Reference Objects , according to the JSON Reference specification, cannot have sibling properties. (It seems the $ref property inside the Path Item Object is not strictly a Reference Object. But it's safest and cleanest to treat it as a Reference Object, and avoid adding any properties alongside $ref).  

  • Path item references require some tricky encoding because of the slashes and curly braces. You'll find it much easier to insert the path item reference if you use code assist, and take advantage of the scope cycling feature. After the  $ref: key, press the code assist hotkey (ctrl+space on Windows) repeatedly to cycle through document, project, and workspace scope. Then you can use type-ahead to filter the suggestion list and find the path you want to insert.

  • Generally, you'll want to ensure that the name of the path item is the same in the referring context as in the referenced path item object. I have seen (but not yet diagnosed) some rendering errors that can occur if these are different. 

Please give this a try and post back to let us know if it worked for you.


Ted Epstein |   |       skype:ted.epstein


Thank you, so much Ted.  Using the code assist helped, as I made error in typing it.  Appreciate your help.

Glad it worked, Jay!  Be sure to check out these resources to learn more about multi-file support in API Studio:


Ted Epstein |   |       skype:ted.epstein

Login or Signup to post a comment