Add swagger to a spring boot application.
In web development, we usually separate the front-end application and back-end application. we expose APIs as a back-end component for the front-end component or third-party app integrations.
Swagger is a library that helps to auto generate the documentation of backend APIs. Moreover, it also supports testing of APIs .
API developers have been using Swagger 2.0 spec to define APIs over past few years. Later it has been donated to Linux foundation and named as Open API specification and a new swagger spec was released with lots of new features and improvements as Open API 3.0.
Lets dive and see how to configure swagger in a spring boot application.
Swagger 2
- Add following dependency to pom.xml file.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>Note:
Due to springfox-swagger2 dependency , documentation of our APIs are now available in JSON format at default url /v2/api-docs
Due to springfox-swagger-ui dependency, APIs documentation gets added at default url /swagger-ui.html
2. Add annotation to the main application that is having main() method.
Here, for an application named “MyExample”
package com.example.myexample;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class MyExampleApplication {
public static void main(String[] args) {
SpringApplication.run(MyExampleApplication.class, args);
}
}3. Dependency springfox-swagger-ui adds APIs documentation endpoint at root url /swagger-ui.html. So we have to make sure our other resource (entity) APIs are not present at root url.
You can achieve this by adding following lines over each ResourceController class. For example for StudentController class
@RestController
@RequestMapping("/api")
public class StudentController{
// your code}
Thats it. You can access swagger2 documentation at following urls.
http://localhost:8080/v2/api-docs
http://localhost:8080/swagger-ui.html
Swagger 3
To enable latest swagger3 in your application, follow following steps.
- Add following dependency to pom.xml file.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>2. Remove the annotation “EnableSwagger2” from the main application , if you had added it while enabling swagger2.
There is no extra configuration required to activate swagger on the spring-boot project like the previous swagger2.
3. Dependency springfox-swagger-ui adds APIs documentation endpoint at root url. So move your resource url away from root url by adding following annotation on controller class.
@RestController
@RequestMapping("/api")
public class StudentController{
// your code}
Thats it. You can access swagger3 documentation at following urls.
http://localhost:8080/v3/api-docs
http://localhost:8080/swagger-ui/
Resources:
