Saving and Versioning Swagger definitions

During my time as an API Product Manager, I found myself constantly looking for ways to make my life easier and more efficient.

One of the problems that I encountered was that it was difficult to share and accurately version my swagger definitions.

I started using SwaggerHub, but I found it to be overkill for the simple Swagger definitions that I was creating.

Eventually, the easiest way for me was to use Github's gist service frequently to push YAML or JSON files and was asking people to copy these into editor.swagger.io to view and manage.

Given that this relationship was quite nice, I thought I could modify the open source Swagger editor to auto save into Gist for me.  This both allows me to continue to share my Gists, whilst removing the need to manually save them there.

After a bit of tweaking, and a bunch of AWS services, I've today pushed live swagger-gist.io.

Get Started:

1. You'll need a github account, so sign up at github.com.
2. Follow the instructions here to generate an access token. Please make sure you grant Gist access when creating the token.
3. Browse to swagger-gist.io and click 'File -> Connect to Github'
4. Enter your github username and the access token that you generated.
5. Click 'File -> Open API Definition' and this will search your Gists for any that have a 'Description' with the word 'Swagger' in it.
6. Click 'Open' and the app will retrieve the JSON gist and render it as YAML.

Note: I suggest saving this access token in your favourite password safe as you may need it across multiple devices.  At this stage I only save it into the browser's localstorage object.

Creating a new Swagger Definition

If you don't have any Swagger as Gist yet, then you'll need to create a one using the instructions below.

For the moment you have to create new definitions manually, but once it's created, the auto-saving will take place. I'll improve this eventually.

1. Browse to gist.github.com and sign in.
2. In the gist description, make sure you include the word 'Swagger' (with the capital S) and make a note of it.
3. The filename can be whatever you desire, just make a note of it.
4. Enter some sample value in the gist (e.g. ABC123) it doesn't matter what it is.
5. Click Create Public Gist.
6. In the URL you will now see something like: https://gist.github.com/johnsmith123/40eea519f479fe27a831d15770255a7f
7. The string of characters after your username is the Gist-ID.  You'll need this next.

Creating the new file in Swagger-Gist:

1. Click 'File -> New'
2. You'll see in the sample file 'info' section, there are 4 elements that should be filled out: - title - x-gist-id - x-gist-filename - x-gist-description
3. The title can be whatever you desire, but the id, filename, and description should match exactly what you created in your sample Gist.
4. Once you've copied the properties, the auto-save will automatically occur after 10s.

That's it! You've now got a swagger definition that is hooked up to Gist.

Next Steps:

• Hook up proper Github OAuth to generate the token and store them in a more permanent store.
• Allow generation of new Swagger docs directly from the editor
• Publish to Heroku (I use Heroku heavily for hosting swagger definitions).
• Migrate code to the latest fork of swagger editor.  It's changed significantly since I started this project.

Tech Tools Used:

Front End: Angular JS Hosting: AWS S3 / CloudFront

Back End: AWS API Gateway -> Lambda -> Gist API.

Shout out to @gojkoadzic who created claudiajs which helped me significantly with writing my AWS API / Lambda code.

If you're interested in finding out more, ping me or comment and I'll write another post.

Originally published on jordwalsh.com on 10 October 2016.