Swagger
Swagger is an Open Source set of rules, specifications and tools for developing and describing RESTful APIs. The Swagger framework allows developers to create interactive, machine and human-readable API documentation.
API specifications typically include information such as supported operations, parameters and outputs, authorization requirements, available endpoints and licenses needed. Swagger can generate this information automatically from the source code by asking the API to return a documentation file from its annotations.
Swagger helps users build, document, test and consume RESTful web services. It can be used with both a top-down and bottom-up API development approach. In the top-down, or design-first, method, Swagger can be used to design an API before any code is written. In the bottom-up, or code-first method, Swagger takes the code written for an API and generates the documentation.
Components of Swagger
Swagger provides a variety of open source tools for APIs, including:
- Swagger Editor- This enables developers to write documentation for, design and describe new APIs as well as edit existing ones. The browser-based editor visually renders OpenAPI specifications, handles errors and provides real-time feedback.
- Swagger Codegen- This gives developers the ability to generate client library code and SDKs for different platforms.
- Swagger User Interface- This is a fully customizable tool that helps engineers generate documentation for various platforms. It can be hosted in any environment.
- Swagger Inspector- This is a testing tool for API documentation. APIs can be easily validated without limits and results are automatically saved and accessed in the cloud.
Benefits of Swagger
In addition to its goal of standardizing and simplifying API practices, a few additional benefits of Swagger are:
- It has a friendly user interface that maps out the blueprint for APIs.
- Documentation is comprehensible for both developers and non-developers like clients or project managers.
- Specifications are human and machine readable.
- Generates interactive, easily testable documentation.
- Supports the creation of API libraries in over 40 languages.
- Format is acceptable in JSON and YAML to enable easier edits.
- Helps automate API-related processes.
History of Swagger
The Swagger API project was created in 2011 by Tony Tam during the development of tools for the dictionary website, Wordnik. The framework was designed to ease API automation and its documentation. The project was then made open source where it gained traction with companies and developers.
In 2015, the company that maintained Swagger, SmartBear Software, helped found the OpenAPI initiative, an organization that is sponsored by the Linux Foundation. A year later, Swagger was renamed to the OpenAPI Specification and was moved to a new GitHub repository.
Swagger is currently the largest framework for designing APIs with a common language. However, a few alternative frameworks that have gained popularity include RAML, APIBlueprint and Summation.
