Table of Contents

• Introduction
• Goals
• The Process
  • Web Server
  • Markdown
  • Swagger UI
• Custom Documentation
  • Creating an Archive
  • Flexibility
• Working Example

Introduction

We’ve looked into a few options for documenting server projects and they’ve all come with their own quirks, limitations, and complexities:

• API Blueprint
  • not pleasant to write
  • when auto generated from an Open API specification having the schemas repeated for each request response makes it difficult to read
  • does allow you to insert your own custom documentation with ease
• Swagger UI
  • only really useful for documenting the API itself
  • links to external documentation, but doesn’t allow documentation to embedded in a clean manner (the JSON flavour)
• DapperDox
  • one of the best Open API to HTML doc generators we’ve come across
  • clear support for custom documentation
  • easy to write new themes
  • broke on a simple response schema, and the community does not seem to be very responsive

Open API (Swagger) is mentioned a lot above, as it’s a well known standard, and a bunch of tools can write and consume it. It therefore makes sense as a baseline to use Open API and work out the best way we can for documenting it.

Goals

There are consumer (e.g. app developers) and producer (e.g us) goals for the documentation.

A consumer will want:

• a system overview
• a clearly documented API
• example resources e.g. payloads

As a producer we want:

• to minimize the amount of work required to generate documentation
• to use well supported tools
• to make it easy to maintain the documentation

The Process

This has brought us to the following solution, which depends on the following:

• a server that supports Server Side Includes (ssi)
• markdown
  • everyone can write it
  • PRs will be clear as its a simple text format
  • limits the author scope to concentrating on the documentation rather than the presentation
• Swagger UI
  • allows the browser to generate swagger docs from an Open API specification
  • well supported
  • easy to integrate by using the latest dist from their repository

Web Server

Our docs are served by nginx on buzz. ssi can be enabled for specific locations.

We have the https://docs.tp.ie domain configured to serve our documentation. It’s a minor level of obfuscation, but it makes it that little bit harder for randomers to find than docs.tapadoo.com.

Markdown

We’re going to use GitHub Flavored Markdown (GFM) as it’s one of the most common versions out there now, and GitHub provide comprehensive documentation for it.

We use markdown-to-html for conversion.

Swagger UI

As mentioned above we are using the latest distribution from the Swagger UI repository. We have a Tapadoo repository that only contains the distribution, and also has some minor modifications so it can be ready to serve our specifications.

These changes are:

• modify the path of the specification to load – by default it loads PetStore.
• turn off schema validation – it’s an HTTP call to a validator, which means we’d need to use absolute URLs for swagger.json.
• hide the topbar – this allows the user to enter a URL to load, but we want to streamline the UI for the current project only.

Custom Documentation

We use markdown for our custom documentation, and using a simple template with a ssi we can then render the resulting HTML in a clear and controlled manner.

Let’s look at an example. Say we had an index page index.md:

# Welcome to Documentation

The documentation is split into three sections:

1. Introduction
2. API Overview
3. FAQs

When we run github-markdown index.md we get:

<h1>
<a id="user-content-welcome-to-documentation" class="anchor" href="#welcome-to-documentation" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Welcome to Documentation</h1>
<p>The documentation is split into three sections:</p>
<ol>
<li>Introduction</li>
<li>API Overview</li>
<li>FAQs</li>
</ol>

We want to use this as the main content of our index.html. This HTML isn’t suitable to be used as a standalone file, so we use a template file with an ssi like so (some bits chopped for brevity):

<!DOCTYPE html>
<html>
<head>
    <link href="static/github.css" type="text/css" rel="stylesheet" />
</head>
<body>
    <div class="container">
        <!--# include file="_index.html" -->    
    </div>
</body>
</html>

We simply redirect the output from the github-markdown command to save it in _index.html: github-markdown index.md > _index.html.

Creating an Archive

Now we bundle the files into a .tgz which can be copied and then extracted on the webserver e.g.

# convert markdown to GFM flavoured Markdown
github-markdown index.md  > _index.html

# create a clean distribution
tar -czf aa-coupon-server-docs.tgz \
    --exclude='README.md' \
    --exclude='*.sh' \
    *

Flexibility

Each project can use this process as it’s lightweight and adjust accordingly. For example, if there are going to be multiple custom files e.g. index.html, faq.html, etc. just add more templates and markdown files to the documentation repository, or write a script to automatically create the templates for example.

Working Example

To see a full example, check out the aa-coupon-server-docs repository, and the results which are on docs.tp.ie.