Configuring Auto Generation of Swagger Documentation

by Online Tutorials Library July 14, 2022

Configuring Auto Generation of Swagger Documentation

Swagger

A Swagger is an open-source tool. It builds around the OpenAPI Specification that helps developers to design, build, document, and consume RESTful APIs. It is the most popular API documentation format for RESTful Web Services. It provides both JSON and UI support. JSON can be used as a machine-readable format, and Swagger-UI is for visual display, which is easy for humans to understand by just browsing the API documentation. The main Swagger tools are:

Swagger UI: It creates interactive API documentation.
Swagger Editor: It is a browser-based editor where we can write OpenAPI specifications.
Swagger Codegen: It generates server stubs (API implementation stub), and client libraries form an OpenAPI specification.

An OpenAPI Specification (formerly known as Swagger Specification) is an API documentation format for REST APIs. An Open API file allows us to describe our entire API, including:

Available endpoints (/users) and operations on each endpoint (GET /users, POST /users).
Operation parameters for each operation.
Authentication methods.
Contact information, license, the term of use and other information

Let’s generate Swagger documentation for our RESTful services.

Step 1: Open pom.xml and add springfox-swagger2 dependency.

  <dependency>      <groupId>io.springfox</groupId>      <artifactId>springfox-swagger2</artifactId>      <version>2.9.2</version>  </dependency>  

Add another dependency springfox-swagger-ui

  <dependency>      <groupId>io.springfox</groupId>      <artifactId>springfox-swagger-ui</artifactId>      <version>2.9.2</version>  </dependency>  

Now we need to configure Swagger.

Step 2: Create a class with the name SwaggerConfig.java and write the following code.

Docket: A builder that is intended to be the primary interface into the swagger-Spring MVC Framework. Docket provides sensible defaults and convenience methods for configuration.

  package com.tutoraspire.server.main;  import org.springframework.context.annotation.Bean;  import org.springframework.context.annotation.Configuration;  import springfox.documentation.spi.DocumentationType;  import springfox.documentation.spring.web.plugins.Docket;  import springfox.documentation.swagger2.annotations.EnableSwagger2;  @Configuration  //Enable Swagger  @EnableSwagger2  public class SwaggerConfig   {  //creating bean  @Bean  public Docket api()  {  //creating constructor of Docket class that accepts parameter DocumentationType  return new Docket(DocumentationType.SWAGGER_2);  }  }  

Step 3: Run the application.

Step 4: Open the browser and type the URI http://localhost:8080/v2/api-docs

It shows the complete documentation in JSON format, as shown in the following image. It is not much easy to read and understand. Swagger has provided it to be used in other systems like API management tools that offer functionality like API gateways, API caching, API documentation, etc.

Configuring Auto Generation of Swagger Documentation

If we want to share the documentation of web service with customers, we can share this JSON file.

Now type the URI http://localhost:8080/swagger-ui.html in the browser. It shows the documentation of the services that we have created.

Configuring Auto Generation of Swagger Documentation

We can also expand the services to see which operations are present in service. In the following image, we have expanded user resource service.

Configuring Auto Generation of Swagger Documentation

Click here to download project

Next TopicIntroduction to Swagger Documentation Format

Configuring Auto Generation of Swagger Documentation

Configuring Auto Generation of Swagger Documentation

Swagger

Difference between Method Overloading and Method Overriding in java

First JavaFX Application

You may also like