Better OpenAPI spec developer experience with Gists

Jarkko Moilanen
Dec 2, 2017 · 1 min read

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

APIOps Global Network for APIOps, a new breed of DevOps to…

APIOps

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

Jarkko Moilanen

Written by

Platform of Trust DX Lead, APItalist (API Economy Consuntant) Founder of: @APIOps, API Economy Hacklab. Author of "API Economy 101" book.

APIOps

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

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

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