dapperdox

README

DapperDox   

Beautiful, integrated, OpenAPI documentation.

Themed documentation generator, server and API explorer for OpenAPI (Swagger) Specifications. Helps you build integrated, browsable reference documentation and guides. For example, the Companies House Developer Hub built with the alpha version.

Features

• Author full documentation in GitHub Flavoured Markdown.
• Document multiple API specifications as a suite of cross-referenced products.
• Seamlessly overlay content onto the automatically generated reference documentation.
• Integrate the built-in API explorer with your APIs and authentication model.
• Proxy your developer platform, allowing full integration of API key management.
• Choose from multiple themes, or create your own.

Documentation and usage

Detailed usage instructions are available on the DapperDox website http://dapperdox.io.

Quickstart

We provide the lastest release builds for the most common operating systems and architectures, which you can download from releases, or you can build from source by cloning this repo.. See downloads for further information.

Build from source

First build DapperDox (this assumes that you have your golang environment configured correctly):

go get && go build

Running DapperDox

Start up DapperDox, pointing it to your OpenAPI 2.0 specification file:

./dapperdox -spec-dir=<location of OpenAPI 2.0 spec>

DapperDox looks for the file swagger.json at the -spec-dir location, and builds reference documentation for the OpenAPI specification it finds. For example, the obligatory petstore OpenAPI specification is provided in the examples/specifications/petstore directory, so passing parameter -spec-dir=examples/specifications/petstore will build the petstore documentation.

DapperDox will default to serving documentation from port 3123 on all interfaces, so you can point your web browser at http://127.0.0.1:3123 or http://localhost:3123.

For an out-of-the-box example, execute the example run script:

./run_example.sh

This demonstrates many of the configuration options available. See configuration.

Acknowledgements

Many thanks to Ian Kent who spiked the Golang implementation of DapperDox as part of a bigger project. His commit history was lost when DapperDox was extracted into a stand-alone project, but its core retains his valuable work.

David Mort for painstaking testing, and bug fixing.

Documentation

Overview

Copyright (C) 2016-2017 dapperdox.com

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.