The Getting Started guide shows you how to download and install DapperDox; how to quickly get an OpenAPI Swagger 2.0 specification rendered, and some useful configuration options to tune the presentation.
Download the latest release of DapperDox for you operating system, and unpack it.
tar -zxf dapperdox-*.tgz cd dapperdox
DapperDox requires little configuration to get started, just where to find your OpenAPI Swagger 2.0 specifications. Configuration parameters can be specified on the command line, or by setting environment variables.
For this example, we will specify the Swagger specification location on the command line:
Alternatively, you can run the example quickstart script
.\run_example.bat on Windows)
in the dapperdox release directory.
This will start serving the example petstore specification included in the DapperDox distribution.
By default, DapperDox will start serving reference documentation on port 3123, so point your web browser at http://localhost:3123
Point DapperDox at the directory containing your Swagger specification using the
-spec-dir configuration parameter,
where DapperDox will look for the file
swagger.json. If your specification has a different filename, specify
this with the
If your specification is broken down into multiple files, with some in sub-directories, then you must point
DapperDox at the parent directory, beneath which it can find all the files it needs. If the main Swagger
specification file exists in a sub-directory of this parent, then configure that using the
For example, consider the following file structure:
/user/api_specs/spec/swagger.json /user/api_specs/operations/get_user.json /user/api_specs/operations/post_user.json /user/api_specs/definitions/user_resource.json
Since the common parent directory of all these resource files is
api_specs, this is where you need to tell DapperDox
to look for specification files:
and because the main swagger specification file is within a sub-directory of the common parent
api_specs, give the
relative path to this using the
You may find that your specification does not load first time if it consists of multiple files
$ref: members. Please refer to the section on resolving references if this is the case.