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.