---
title: "Single sourcing the Swagger spec and main documentation using Jekyll"
date: 2015-12-03
description: "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..."
canonical_url: https://idratherbewriting.com/2015/12/03/overcoming-doc-fragmentation-with-swagger-spec/index.html
---

> For AI agents: a documentation index is available at https://idratherbewriting.com/llms.txt. Markdown versions of all pages are available by appending .md to any page URL.

# Single sourcing the Swagger spec and main documentation using 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: [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?