Published in


Better OpenAPI spec developer experience with Gists

I’ve been using OpenAPI spec to design APIs for a year or so. I’ve used it to describe existing APIs as well. What I am missing is more dynamic tools to write Getting started package in the description section in spec. Getting started package is there to help API consumer to get started fast, show examples (code snippets) how to do basic operations. Gists offer way to display code to end-users. Code is what developers like to read and see.

In other words, getting started section is there to lower the barrier, offer quick start and increase developer satisfaction. With the current options I find it hard to write good getting started section in the spec.

Gists to the rescue

Ability to add gists would improve the possibilities to write better instructions for API consumers. Gists are supported by multiple platforms such as Medium. Of course those two (Medium and OpenAPI spec renderers) are not the same and can not be compared directly. Using gists would ease the updates of the getting started as well.



APIOps Global Network for APIOps, a new breed of DevOps to support lean, business-oriented and developer friendly APIs

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Jarkko Moilanen (PhD)

API, Data and Platform Economy professional. Author of "Deliver Value in the Data Economy" and "API Economy 101" books.