In the previous post in the series we covered the basics behind what is Swagger and what it looks like. This time we’ll go over some benefits of using Swagger.
Common Language - As a specification, Swagger has a set of rules that are easy to follow and understand. Utilizing it helps having a common ground between API producers and consumers. Being (development) language-agnostic means easier interoperability between applications.
Human/Machine Friendly - Supporting both JSON and YAML as formats, Swagger ends up being easy to read and write by both humans and machines. For the users, YAML is the easier format to use being less verbose than JSON. Users can also opt to use one of several visualization tools to view a rendered version of the documentation and interact with it. For machines, either can be parsed using the various libraries out there allowing for powerful integrations.
API Lifecycle - Whether you’re looking to replace a manually maintained documentation of your API to your users or looking to take control of your entire API lifecycle of your application, Swagger is there for you. Design, documentation, code generation, testing, API management, monitoring - pick one, pick many, the choice is yours.
Development Process Integration - You may have an existing API or you may be looking to create a new API, but either way Swagger fits your needs. Use one of the many language integrations out there to generate the Swagger documentation right from your code, or use Swagger Editor to plan and design your API to be used as your source of truth. You can even move from an existing API to a contract-first approach should you want. Lately, we’ve introduced a new approach that allows you to keep the Swagger definition and the code loosely coupled yet still hooked together. This is provided by either swagger-node (for node.js) or swagger-inflector (for Java).
Community Driven - Ever since Swagger first became public, it was influenced by user requests. Swagger 2.0 was driven by an open group of 400 people coming from major companies, small start-ups and even some self-representing users. Everyone could voice their opinion, bring up their pain points and push the spec forward. We now have a dedicated github repository for the spec where our users can open feature requests, comment on existing requests and generally affect the future of Swagger.
Ever-Growing Toolset - There are countless tools supporting Swagger both open source and commercial. The various tools are there to promote language integrations and plugging in Swagger to different parts of the API lifecycle. More and more tools are added on a regular basis covering more frameworks and new aspects in the lifecycle.
In the next installment we’ll go over a few ways of getting your first Swagger definition ready for use.