It’s official… we’ve got the moves like Swagger! It’s been the most requested feature for a while, and we wanted to make sure we got it right.
Over the past year, Swagger has made a ton of progress. It was transferred to The Linux Foundation and renamed to the Open API Initiative. It went from being something they were intrigued by to something they actively implemented. And for us, it went from beta feature to first class citizen.
For those of you who aren’t familiar with Swagger/OAI: it’s a way to describe your RESTful API. It’s meant to be machine and human readable, and can be used to either design or document your API.
Generating a Swagger File
There’s many ways to generate a Swagger file: using the official Swagger Editor, from your code, using your own build tool… the list goes on.
We think there’s a few important factors when generating a Swagger file: it should be as close to your code as possible, it should be easy to update, and it should be easy to deploy. With that in mind, we created Swagger Inline. This allows you to comment your API right in the comments above the code, and publish it to the web with one command.
Here’s how it works. Start by installing oai (that’s short for Open API Initiative):
npm install oai -g
Once it’s installed, go to the directory you’re looking to document and type:
oai init
This will walk you through how to create a Swagger file!
Using On ReadMe
Have a Swagger file? Just curious? Check out our Swagger page to get started! We’re excited to support Swagger, and looking forward to helping you build awesome APIs!
