Make Selenium Easy

Introduction To Swagger API Documentation


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.

Introduction to Swagger

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 /usersPOST /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:-

  1. Available endpoints or APIs grouped in collections
  2. A brief description of API
  3. Expected status codes
  4. Sample request and response payload
  5. Expected values for fields
  6. Model or metadata about fields in the payload
  7. Easily readable and understandable by human
  8. 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.

Find all Selenium related posts here, all API manual and automation related posts here, and find frequently asked Java Programs here.

Many other topics you can navigate through the menu.

Author: Amod Mahajan

My name is Amod Mahajan and I am an IT employee with 6+ years of experience in Software testing and staying in Bengaluru. My area of interest is Automation testing. I started from basics and went through so many selenium tutorials. Thanks to Mukesh Otwani as his tutorials are easy and cover basics to advance. I have habit of exploring concepts by deep diving. I used to make notes. I thought of sharing my knowledge through posts and now I am here. #KeepLearning #ShareLearning

Leave a Reply

Please wait...

Subscribe to new posts to become automation expert

Want to be notified when my new post is published? Get my posts in your inbox.

Introduction To Swagger API Documentation

by Amod Mahajan time to read: 2 min
%d bloggers like this: