I envied Stripe’s beautiful API documentation. I figured out how they do it. Maybe not exactly how they do it, but something that gets you 99% there.  Basically, it is Slatehttps://github.com/lord/slate/ but you need some extra tooling.

With API Docs – we’ve tried a few ways – markdown, jsondoc, Swagger and OpenAPI3.0. What works for us is Swagger, mainly because of all the tools available to generate client and server stubs, and to also generate good-ish API documentation. OpenAPI 3.0 is a better spec than Swagger in that there are more tags for API information but there isn’t anywhere near the tools available to create useful stuff from OpenAPI 3.0. (if any)

It seems stupid now, but in the beginning, we did a code first, design second approach when creating API’s – and guess what, the backend team didn’t want to write documentation.  It created a lot of friction for the API users, mainly the Front-end team, trying to understand the API spec. So we tried maintaining Markdown, then went to Swagger and things because much easier.  It encouraged a design first approach. This became the easiest method for all the Dev team. Write some YAML, then run that through Swagger and presto, you’ve generated client stubs, server stubs, and some reasonable documentation. And it is all in Git.

But what Swagger produces is not as beautiful as these:  https://monzo.com/docs/, https://www.capitalone.co.uk/developer/api/, https://skyscanner.github.io/slate/, https://bestbuyapis.github.io/api-documentation/

Basically, these guys are using Slate. But you need a few other things to pull it all together.

  1. The Dev maintain the Swagger YAML in Git, adding methods as they get developed. They like doing this because it means typing less code because from the YAML generates the stub code.
  2. When the Product team want to release a new version of API docs, the pull the YAML from Git. They copy it into SwaggerHub. They edit all the narrative parts of the API. They like the WYSIWYG documentation editing because they don’t have to struggle too much with YAML syntax. They commit back any changes to Git.
  3. The Product team then pull the Swagger JSON format from SwaggerHub (SwaggerHub convert YAML to json)

#Pull the json from swagger hub – you can find your authorisation key under administration settings

curl  -H “accept: application/json” -H Authorization:GET-THE-KEY-FROM-SWAGGERHUB_ADMIN-SETTINGS  https://app.swaggerhub.com/apiproxy/schema/file/MY_ACCOUNT/MY_API/MY_VERSION/swagger.json?pretty=true >/tmp/api.json

  1. Convert to Slate markdown language. Widdershins does the job nicely.
node widdershins.js /tmp/api.json -o …slate-master/source/index.html.md markdown
  1. Use Slate to create all the beautiful static API html documentation pages.
bundle exec middleman build

Job done! Beautiful API documentation, that looks nearly as good as Stripe. The Dev team like it. The Product team like it. Happy.

Read Why an API is not enough with SMS messaging.

Like this?