Single sourcing the Swagger spec and main documentation using Jekyll
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: [email protected]
url: https://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: [email protected]
url: https://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: [email protected]
url: https://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?
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.