Stoplight Displays API Definitions By Default With Their API Doc Service
06 Sep 2016
I was doing some maintenance on my bots and APIs research, and processing the information for the bot analytics provider Botlytics, and as I was going through their API I noticed the prominent placement and availability of OpenAPI Specs for the API.
Making your API definitions as prominent as possible is something I have been advocating for some time now, something I reinforced again recently by asking API providers to make sure and show as an icon, or other very visual element. This is a very important part of the API life cycle, that when also supported as a default feature by API service providers, just keeps giving to the API community, and helps makes it truly more open, consistent, while also helping it be more machine readable. (shouldn't everything API be machine readable? *cough* hypermedia *cough*)
When Apiary introduced this feature to their API customers by default I wrote about it, and I also wanted to take the time and give a nod to the Stoplight.io team for doing this with their API Docs--making OpenAPI Spec definitions available in such a prominent location by default. API providers don't always have the time to think of all the little details (which is why I write about things on API Evangelist), so it is super critical that API providers help raise the bar like this when possible.
If you are looking for the quickest way to deploy machine readable API definitions + API docs for your API I recommend downloading Stoplight's Prism, fire up your API in Postman, make calls to all your API endpoints, and Prism, Stoplight, and API Docs will do the heavy lifting for you