Adding Swagger API documentation

This week I have finally ended up researching about current state of API documentation as I decided to write one for Webhook Relay.

Few years ago I have worked a bit with Swagger spec but found the tooling quite incomplete and embedding wasn't as nice as their marketing wanted you to believe.

This time I have looked at:

• OpenAPI
• Swagger

Seems like both OpenAPI and Swagger can be converted from one to another, but I chose Swagger as it just seemed to be a safer choice.

Editor

I started with https://apiary.io but quickly discovered that the web editor is quite lacking, there are no features as instant validation or auto-completion. Looking at swagger editor I had the same feeling. Main problems with the online editors:

• not your typical development environment
• lack of auto-completion
• while they do have auto-save functionality, you can't compare it to Git

After a quick search in VSCode extension I have found swagger viewer: https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer. It offers pretty much the same functionality as a web version but changes can be seen instantly and you still have to keep all your favorite keyboard shortcuts :)

Embedding

Embedding seemed also quite a challenging step. There are lots of solutions, but you need to choose what's best for you:

• Swagger UI (https://github.com/swagger-api/swagger-ui) - probably one of the most popular approaches, although didn't find the styling nice and didn't want to invest time into creating a theme.
• A fantastic custom Swagger UI - https://github.com/jensoleg/swagger-ui but the project does seem to be abandoned.
• Apiary.io hosting - each project gets its own 4th level subdomain which is neat, but a bit unnecessary in our case as we already have documentation website.
• Spectacle (https://github.com/sourcey/spectacle) - seems to be popular and I think I was going for this one but in the changed my mind.

Honestly, I thought I will probably just have to go the theming approach, but I accidentally found this excellent project Redoc:

https://github.com/Rebilly/ReDoc

With Redoc whole integration looks like:

<div id="redoc"> </div>
  
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> 
<script>
    Redoc.init('https://raw.githubusercontent.com/webhookrelay/swagger-webhookrelay/master/swagger.yaml', {
        scrollYOffset: 60,
        hideDownloadButton: true
    }, document.getElementById('redoc'))
</script>

So, we have a winner :) The end result looks like this: https://webhookrelay.com/api-reference/ although it's still in progress, there are some missing API calls that need to be documented such as domain reservation, sub-account management and tunnel ingress rule configuration. Still, I think Swagger + Redoc is a great pair. Combined with hosting it on Github you end up with an end-to-end solution.