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..."
Sponsored
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, agent skills, tech comm careers, and more. Check out my AI courses for more on the latest in AI and tech comm. If you're looking for info about documenting APIs, see my API documentation course.
If you're a technical writer and want to keep on top of the latest trends in tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me.
Finally, I want to note a couple of things. I usually write the first drafts of my posts myself and then use AI to improve accuracy, clarity, and detail in places, so my writing is a mix of human and AI. (Hopefully that's not too off-putting.) Also, the opinions I express on my blog are my own perspectives, not those of my employer.