[OAS Compliance] Path Item External Definition

(Erik Hansen) #1

OAS2 supports $ref in the path item object, but this does not appear to be supported by Stoplight in either the Design or Read views. Starting from a clean project that has the sample ToDo API defs, I add a new model file with the following content

The reason for “~1todos” in the $ref path is because the ~1 is the escaped JSON Pointer representation of a forward slash in the path name “/todos”. RFC 6901 and better described here.

Since this path reference is valid according to OAS, I would like to see at a minimum that the Stoplight rendered documentation properly displays the reference. I would also like to see the Design view present $ref as an option for the path so that I don’t need to drop to JSON/YAML.

The motivation for performing this external ref is so that I can split my API definition files along micro-service lines (managed by separate teams) and then create a top level OAS full of references to provide a single reference doc that encompasses my API.