Powerful IDE for API-first design, documentation and development.

Start my Free Trial

There are some blog posts and tutorials online suggesting that Swagger-OpenAPI 2.0 allows $ref elements in any context that expects an object. You might have seen error markers in API Studio, saying object has properties "$ref" which are not allowed, and wondered why these references are not valid.

In fact, the OpenAPI Specification only allows $ref properties in four specific contexts. You can use a reference as a replacement for any of the following object types:

The Swagger specification group has confirmed that references are limited to these four cases. Non-conforming references may work with some Swagger tools and services, but may not work with others (including tools supplied by the Swagger project itself).  

Accordingly, RepreZen API Studio enforces strict compliance with the specification, to ensure that your API specifications are portable across editors, and work well with code generators, documentation tools, and other components in the Swagger-OpenAPI ecosystem. 

RepreZen API Studio provides comprehensive support for multi-file Swagger projects, including cross-file references. Content assist, hyperlink and quick outline navigation, code generation, and the live documentation view are all multi-file aware.  

You can see Swagger-OpenAPI references in action here: