Looking for example of multiple path files referenced each with multiple path items : RepreZen API Studio Community & Support

J

Jay Gopalan

started a topic 6 months ago

Hello,

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

Users (/v1/users)
Accounts (/v1/accounts)
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:

/users:

$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?

Thanks.

Ted Epstein

said 6 months ago

Hi Jay,

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

Each path reference needs its own key within the
paths
object.
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.