Users have occasionally asked this question, so we're posting the common answers here.
There could be several reasons why DapperDox fails to load your specification, not because there is anything wrong with your specification or DapperDox per-se, but DapperDox may need a little help in doing the right thing. These are generally straightforwards to resolve.
The two most common things which trip new users up are:
title members for definitions (or inline schemas)
DapperDox needs to know what name to give a response or request-body resource in the reference documentation it produces. This might be inferable when reading the actual specification file, but once the specification is processed by go-openapi (the parser used by DapperDox) this information is lost, since it is part of the specification structure, and not explicit. Also, this may not be what you want to call the resource.
DapperDox therefore makes the
title member of a definition or schema mandatory, thereby making the name of a resource explicit. You should probably adopt a naming standard for these resource names, such as kabab-case, or camelCase.
See resource definitions for further details.
Cannot load referenced specification sub-files
DapperDox loads its specification resources over HTTP or HTTPS, and you may find that the domain name (and perhaps port number) that you have used in your specification does not match the domain name and port from which DapperDox is running and serving content.
This is often the case when you have a specification that is correctly written for a production environment, but also needs to work in a local, development or test environment.
To resolve this issue without having to edit the specification or maintain different versions for different environments, you can have DapperDox rewrite specification URLs on the fly. To do this, use the
-spec-rewrite configuration parameter. See rewriting specification URLs for full details.