Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,220

Adobe Robohelp

Single sourcing the Swagger spec and main documentation using Jekyll

Dec 3, 2015 • api-doc, jekyll

You can use Jekyll to populate variables in both your Swagger spec and main documentation. This allows you to single source your content into both of these outputs in a more efficient way.

One of the challenges with Swagger is that the output duplicates a lot of the descriptions that already appear in your main documentation.

In your Swagger spec, you list your resources and endpoints, with descriptions, code samples, and other content. Most likely all of this content already exists in your main documentation.

As a result, you may end up either copying and pasting the same descriptions from your main doc into your Swagger spec file. Or you end up trying to generate Markdown from the Swagger spec that you can then paste in your documentation. Either way, it seems like you end up copying and pasting from one output to another.

To eliminate this inefficiency, here’s the approach I’m trying.

In Jekyll, create a YAML file (e.g., acme.yml) in the _data folder. Add key-value pairs in it like this:

description: "This is a description of my API..."

Put your Swagger spec file inside your Jekyll project. Reference the description stored in the data file:

---
swagger: '2.0'
info:
  version: 1.0.0
  title: My API
  description: {{site.data.acme.description}}
  contact:
    name: Tom Johnson
    email: tom@idratherbewriting.com
    url: http://idratherbewriting.com

Add Jekyll frontmatter tags so that Jekyll will process the file, but don’t use your regular layout.

---
layout: none
---
---
swagger: '2.0'
info:
  version: 1.0.0
  title: My API
  description: {{site.data.acme.description}}
  contact:
    name: Tom Johnson
    email: tom@idratherbewriting.com
    url: http://idratherbewriting.com

When Jekyll builds the site, it will populate those variable fields ({{site.data.resolve.res_api.description}}) with content.

The result looks like this:

---
swagger: '2.0'
info:
  version: 1.0.0
  title: My API
  description: This is a description of my API..."
  contact:
    name: Tom Johnson
    email: tom@idratherbewriting.com
    url: http://idratherbewriting.com

In the main documentation, for the description of the API, you would also use the same variable:

## Welcome to my API

{{site.data.acme.description}}

This way you will be populating both the Swagger spec file and your main documentation from the same source.

I did a small test and this approach seems to work. Now I’m just implementing the rest of my Swagger spec with this approach. What do you think? Is this a good approach, or is there a better way to avoid the duplication?


Get new posts delivered straight to your inbox.

Subscriber count: 3,220

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.