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.

Home office version

As hard as I tried, using dep tool, and using different git remotes I could not avoid renaming the imports. The final straw was creating the Docker container, it has to do a go get, which pulls the original dapperdox. It feel hacky but it works...maybe revisit when vgo matures

To see the container in action look at https://gitlab.digital.homeoffice.gov.uk/cto/api-directory

### Description

The Dockerfile contains the bulk of the detail. It basically :

• Creates the dapperdox binary in a container stage
• Copies the binary into the second stage container
• Copies the base assets (templates, css etc)
• Prepares a assets/sections directory for copied in project markdown
• runs a bash script to move files around in the directory structure

run.sh

This file copies spec files and md file around. When this container is run a volume is created and mapped to /specs. Git-sync containers write to this volume, but the files are in the wrong structure. This script is a simple fix.

quay

The drone file pushes this to the quay open repository.

Running locally

sh bin/buildDocker.sh

sh bin/runDocker.sh

open http://localhost:3123

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..

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.