Resolving specification references

It is common that a specification that is split over multiple files will fail to load the first time, caused by its $ref members not resolving to the address that DapperDox is serving the files from.

To correct this, you can tell DapperDox to automatically rewrite all specification references so that they correctly resolve to the running DapperDox instance.

For example, if the above example specification has been written with as its base URL, such that the main swagger specification would be found at, and if DapperDox is serving files from address http://localhost:3123, at the directory /users/api_specs/ and down, then we need to rewrite all references to in the specification as http://localhost:3123/.

To do this, pass the -spec-rewrite-url option to DapperDox:

-spec-rewrite-url= \

This rewrites the part of a URL that matches the value given by -spec-rewrite-url as the value given by -site-url.

Note that only absolute $ref references are allowed in a Swagger specification. Relative references in JSON files generally do not resolve consistently, because the concept of what the reference is relative to changes from file to file.

See Rewriting specification URLs for further details.