Support for OpenAPI Documents with External References
OpenAPI documents with external references are supported for both HTTP- and HTTPS-based URLs.
Note the following guidelines:
- The base URL for all references must be the
same:
http://dummyhost/resources/openapi/main.json http://dummyhost/resources/openapi/reference.json
orhttps://dummyhost/resources/openapi/main.json https://dummyhost/resources/openapi/reference.json
- The protocol must be either HTTP or HTTPS for all references. (No redirections for HTTP to HTTPS or vice versa.)
- The URLs must be unprotected (that is, without authentication).
- The references are supported for both relative and absolute URLs.
Examples of both references are as follows:
Absolute Reference Relative Reference "Request": { "$ref": "http://dummyhost/resources/openapi/RequestReference.json#/components/schemas/ReferredSchema" }
"Request": { "$ref": "RequestReference.json#/components/schemas/ReferredSchema" }
- The references are supported only at the schema level (not supported at the path level).
- Only the paths associated in the main OpenAPI document are considered. Any paths in references are ignored.