Swagger – The emerging API Framework
Avakash Dekavadiya
APIs are important component of almost every project. Most of the apps use APIs to make them lightweight by moving heavy logic at server side to ensure smooth and cutting-edge user experience. Even today, people use their own implementation for API specification, which makes all the API specifications different all across the world. It also leads to lot of ambiguities. Swagger is the solution for this problem.
Swagger is standard and eminently useful framework to Describe, Design, Build, Document, Visualize and Consume RESTful APIs. By the introduction of initial major version of Swagger in 2012, it has resolved the problem of specifying the REST APIs and is easy to understand and use. Swagger is ambiguity free.
The swagger specification is based on the OpenAPI Specification (OAS) and is developed in an open, transparent and collaborative community to standardize the way RESTful interfaces are defined. The primary initiative is focused on creating, evolving and promoting a vendor neutral description format.
Swagger can be used by everyone for every kind of user roles:
- Project lead/manager
- Can easily design and specify the APIs
- Developer(backend and mobile both)
- Mobile team can easily mock all the APIs and can continue the development while API are under development mode in server
- Client (technical and semi-technical)
- With good technical knowledge
- With partial technical knowledge
- QA
- Can get all the APIs with specifications at one place and test directly within the browser
Specification is a unique attribute of Swagger. It clearly defines each and every parameter and all the aspect to cover every possibility of specifying the API. It allows to specify all kind of specs at one place in one document. It also provides easy Editor which helps to write the specs and provides a user friendly GUI for each API.
It provides code generation functionality to generate client and server side code to kickoff the project with all the API specification in code. It supports almost all languages which are widely used all over the world.
Also, it gives browser UI to visualize the APIs which can be useful for less technical users. Additionally, you can test each API directly from the browser by providing necessary parameters and observe the response.
Figure 1 & 2 demonstrate how easily APIs can be viewed with simple & clean UI in any browser without addition of any extra tool/software.
Figure 1 API Visualization
Figure 2 API Visualization
- The specification is human and machine readable. Thus, it removes the middle layer that was used earlier for conversion between them.
- Swagger specifications are unique and firm. All teams like documentation team who defines the initial APIs, server team who writes the backend code for RESTful APIs and app developers can be in sync. This makes the team fast and efficient.
- Figure 3 API Specification
- It is a language agnostic. Irrespective of programming language used for implementation of REST API, the behaviour will be same as described in specs.
- Any user can easily understand and consume services without any prior knowledge of server implementation or access to the server code.
- Gives clear insight into how the API responds to various parameters and situation. Another advantage is the ability to generate the specs from the existing system/project.
- One of the major advantage is that it is open source, so everybody has the access of code and can also modify it if required.
- Comprehensive and intelligible for developers and non-developers.
The current major version is Swagger 2. For the next major version Swagger 3, the implementor draft is released. So no major changes is expected after the 3rd version, only minor fixes and syntax change may be there. It is expected to be released in next 6-9 months.
Swagger is improving continuously with the constant efforts by the open community worldwide and has a strong chance to become a de facto API specification tool as git is there for version control.
P.S: Swagger is donated to OpenAPI, so newer version will now be called as OpenAPI specification 3.0 making the version 3 Swagger 3 and OpenAPI 3 will be the same.
