Swagger (okay, now the "Open API Initiative"... more on that later!) is a framework for describing your API using a common language that everyone can understand. Think of it as a blueprint for a house. You can use whatever building materials you like, but you can't step outside the parameters of the blueprint.

There are other available frameworks that have gained some popularity, such as RAML, APIBlueprint, and Summation. But Swagger provides more benefits than just helping create clear documentation.

• It's comprehensible for developers and non-developers. Product managers, partners, and even potential clients can have input into the design of your API, because they can see it clearly mapped out in this friendly UI.
• It's human readable and machine readable. This means that not only can this be shared with your team internally, but the same documentation can be used to automate API-dependent processes.
• It's easily adjustable. This makes it great for testing and debugging API problems.