Updated March 29, 2023
Introduction to spring-boot swagger
Spring boot swagger is the open-source project which was used in java to describe documents of restful API; it is extensible with the new technology and HTTP beyond protocols. Sprint boot swagger will provide a user interface that was used to access the restful services using any web browser; we need to enable swagger in our spring boot application. We have to enable the swagger in our spring boot application by adding the dependency in the pom.xml file. It is a tool and complete framework used to develop framework that represents web services.
What is spring-boot swagger?
- Spring boot swagger is mostly used in API for visualizing; swagger UI also provides the sandbox for front-end development.
- We can say that the swagger is the tool used to develop our project’s complete framework.
- While we have to define spring-boot swagger in our project or application, the user or consumer is interacting with the project using remote service with minimal implementation logic.
- In swagger, we have to remove the guesswork.in service to avoid the unnecessary work of our project.
- Using javascript and asset of CSS, we have to generate the documentation dynamically from API of swagger compliant.
- The current version of swagger is defining the asset of CSS and javascript.
- Spring boot swagger UI allows the other developers to interact with the resources of API without using any implementation logic.
- Swagger is also known as the specification of OpenAPI. We have using multiple swagger annotations to develop our application using swagger are as follows.
- ApiOperation
- ApiResponses
- ApiParam
- ApiModel
- ApiModelProperty
- Above are the swagger annotation we used at the time of project development using spring boot swagger.
- At the time of using annotation in swagger, we need to use the “@” sign before swagger annotation.
- ApiOperation annotation is used to describe the rest of API. It will describe the operation against a specific path using the HTTP method.
- We have used value, notes, and nickname annotation parameters while using ApiOperation annotation.
- ApiResponses annotation is used to describe the rest of API expected responses. This annotation is used to describe the response of concrete.
- We have using the ApiResponse parameter while using ApiResponses annotation in the swagger application.
- ApiParam annotation is used to describe the rest API which was exposed. We have used value, required, and default value annotation parameters while using ApiResponses annotation in the swagger application.
Use spring-boot swagger
- To use swagger in our project, we need to create a maven project and need to add the following dependency in the pom.xml file.
<modelVersion>4.0.0</modelVersion> -- Start and end of modelVersion tag.
<groupId>com.springbootswagger</groupId> -- Start and end of groupId tag.
<artifactId>springboot-swagger</artifactId> -- Start and end of artifactId tag.
<version>0.0.1-SNAPSHOT</version> -- Start and end of version tag.
<packaging>jar</packaging> -- Start and end of packaging tag.
<parent> -- Start of parent tag.
<groupId>org.springframework.boot</groupId> -- Start and end of groupId tag.
<artifactId>spring-boot-starter-parent</artifactId> -- Start and end of artifactId tag.
<version>1.4.1.RELEASE</version> -- Start and end of version tag.
</parent> -- End of parent tag.
<dependencies> -- Start of dependencies tag.
<dependency> -- Start of dependency tag.
<groupId>org.springframework.boot</groupId> -- Start and end of groupId tag.
<artifactId>spring-boot-starter-web</artifactId> -- Start and end of artifactId tag.
</dependency> -- End of dependency tag.- We have used the above dependency while using swagger in our project or application.
- Also, we need to use the annotation name @EnableSwagger2 to use swagger in our application.
- Enable Swagger is a very useful annotation; it is used to enable swagger for our swagger application.
- We also need to use docket bean to configure swagger for our swagger application.
- We have defined docket bean using the select method in swagger; we are getting API selector builder instance using this method.
- ApiSelectorBuilder is used to configure the endpoints which were exposed by the swagger.
- ApiSelectorBuilder is also used to provide control on endpoints that were exposed by swagger.
- Using path selector and request handler selector, we have to configure the predicates of handler requests.
- There are multiple types of annotation available in swagger, which was we have used at the time of developing the swagger application.
Create the Application
In the below example, we have to create the swagger application are as follows. Below is the step-by-step procedure to create a swagger application is as follows.
- Create a project template using a spring initializer and give the following name to the project metadata.
Group – com.example
Artifact name – springbootswagger
Name – springbootswagger
Description – Project of spring boot swagger
Package name – com.example.springbootswagger
Packaging – Jar
Java – 11
- After creating a new project, extract the project. After extracting, open the project in the spring tool suite.
- After opening the project, add the swagger dependency in the project. We have to add the following dependency to the project.
<dependency> -- Start of dependency tag.
<groupId>io.springfox</groupId> -- Start and end of groupId tag
<artifactId>springfox-swagger2</artifactId> -- -- Start and end of artifactId tag. <version>3.0.0</version> -- -- Start and end of version tag.
</dependency> -- End of dependency tag.
- After adding a dependency, add code in the main java file.
@RestController
public class SpringbootswaggerApplication { -- Class of application
@RequestMapping (value = "/products", method = RequestMethod.GET)
public List<String> getProducts () { -- Get list of products
List<String> productsList = new ArrayList <>();
productsList.add ("Sugar"); -- Add product as sugar.
productsList.add ("Almond oil"); -- Add product as almond oil.
return productsList; -- Return list of products.
}
- Clean and build the project.
- After entering the below URL in the web browser to see the functionality of swagger.
http://localhost:8080/swagger.html
Project Structure
- Below is the project structure of the swagger application is as follows. The below example shows the project structure of the swagger application.
- The project contains the following structure.
Conclusion
Spring boot swagger is an open-source project which was used in java to describe documents of restful API. In swagger, we have to remove the guesswork in service to avoid unnecessary work from our project. Therefore, we have used multiple annotations in the swagger project.
Recommended Articles
This is a guide to spring boot swagger. Here we discuss What is spring boot swagger and How to create the application along with the project structure. You may also have a look at the following articles to learn more –
