Many APIs are developed to build a Web-based application. We must have proper API documentation. Many projects maintain it in the Postman tool, word, a web page, etc.
Swagger is another tool for the same even more than just that. You can relate Swagger API doc with Javadoc.
Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document, testing and consume REST APIs.
Swagger was created by the team behind the original “Swagger Specification”, which has since been renamed to the OpenAPI Specification.
Swagger provides an interactive HTML document containing information of APIs with JSON and YAML payloads. Developers needs to use Swagger tools to generate Swagger API document. Swagger UI tool visualizes OpenAPI Specification definitions in an interactive UI.
OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:
- Available endpoints (
/users) and operations on each endpoint (GET /users,POST /users) - Operation parameters Input and output for each operation
- Authentication methods
- Contact information, license, terms of use and other information.
API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines.
I will more focus on understanding and testing APIs using Swagger documentation.
Pet swagger is a good example to understand a typical swagger document. A swagger document can be hosted publicly or on-premises of an enterprise.
If you compare it with other API documentation such as RestFul Booker or GoRest you might understand the above swagger document but Swagger is much easier than other API documentation.
Good API documentation should contain:-
- Available endpoints or APIs grouped in collections
- A brief description of API
- Expected status codes
- Sample request and response payload
- Expected values for fields
- Model or metadata about fields in the payload
- Easily readable and understandable by human
- Automatic update in specification if any change in API
A Swagger API documentation provides all of the aboves. But it provides more than that. We can test APIs using the swagger document within the document itself. We can have authorization mechanism in a Swagger document and hit any listed API easily.
A swagger document contains base URL info with schemes( HTTPS or HTTP).
On expending API row, we can get the HTTP method, base path, sample payload with default values or type of value,metadata etc.
You can see more information abiut fields by clicking on Model.
It also lists expected response code with message as well.
How to perform API testing using a Swagger document will be explained in next post.
You can subscribe to my YouTube channel RetargetCommon to learn from video tutorials.
If you have any doubt, feel free to comment below.If you like my posts, please like, comment, share and subscribe.#ThanksForReading
#HappyLearning