Like RAML, the Swagger specification, or OpenAPI specification, is a specification used to define RESTful Web Service APIs. Springfox is a library used to create the RESTful API documentation in Spring, implement the Swagger specification. In this tutorial, let’s find out how to create RESTful API documentation using Springfox for Swagger in Spring Boot.
First of all, we need a Spring Boot project as an example:
To work with Springfox for Spring Boot, you just need to add the springfox-boot-starter dependency as follows:
|
1 2 3 4 5 |
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency> |
Suppose, I now have a controller that defines an API for managing student information
simply as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
package com.huongdanjava.springbootspringfox; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping(value = "/student") public class StudentController { @GetMapping(value = "findById") public String findById(int id) { return "Khanh"; } } |
By default, if you now run this Spring Boot application and access the address http://localhost:8080/swagger-ui/index.html, you will see the following results:
As you can see, by default Springfox will scan all the controllers included in our application to generate documents for the APIs defined. BasicErrorController is Spring Boot’s built-in controller and StudentController is the controller that I’m defining.
To custom controller, request URL will be Springfox generate RESTful API documentation, you can define bean of Springfox’s Docket class. Springfox Docket is a configuration object for creating RESTful API documentation using Springfox.
For this example, I will add the configuration for the Springfox Docket class as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
package com.huongdanjava.springbootspringfox; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.annotation.Bean; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @SpringBootApplication public class SpringBootSpringfoxApplication { public static void main(String[] args) { SpringApplication.run(SpringBootSpringfoxApplication.class, args); } @Bean public Docket studentAPI() { return new Docket(DocumentationType.OAS_30) .select() .apis(RequestHandlerSelectors.basePackage("com.huongdanjava.springbootspringfox")) .paths(PathSelectors.regex("/student.*")) .build(); } } |
Here, I define Docket with OpenAPI specification 3.0.
The select() method returns us the ApiSelectorBuilder object, so we can use this ApiSelectorBuilder object with the apis() and paths() methods to filter which controllers and which methods should be used to create RESTful API documentation.
As you can see, in the path() method, I used the PathSelectors object with the regex() method to filter the creation of RESTful documentation only for the request URL “/student”.
Now, if you run this Spring Boot application again and request to the URL http://localhost:8080/swagger-ui/index.html, you will see the following result:
As you can see, here Springfox just creates a document with information about our StudentController.
If you click on the GET request “/student/findById” of the student-controller, you will see the following results:
As you can see Springfox has used some default values to create the document for our StudentController according to Swagger’s standards.
In addition to the default values that Springfox has generated, Springfox also supports allowing us to customize our RESTful API documentation.
We can add some other information about our APIs, for example, contact information as follows:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
package com.huongdanjava.springbootspringfox; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.annotation.Bean; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @SpringBootApplication public class SpringBootSpringfoxApplication { public static void main(String[] args) { SpringApplication.run(SpringBootSpringfoxApplication.class, args); } @Bean public Docket studentAPI() { return new Docket(DocumentationType.OAS_30) .select() .apis(RequestHandlerSelectors.basePackage("com.huongdanjava.springbootspringfox")) .paths(PathSelectors.regex("/student.*")) .build() .apiInfo(metaData()); } private ApiInfo metaData() { return new ApiInfoBuilder() .title("Spring Boot Swagger") .description("An example about Spring Boot and Springfox for Swagger") .contact(new Contact("Huong Dan Java", "huongdanjava.com", "huongdanjava.com@gmail.com")) .build(); } } |
In the example above, I added some information like title, description, and contact to our document.
Result:
We can also customize the document for the API by adding some description about it, the data returned.
We do this by modifying StudentController using Swagger’s @ApiOperation, @ApiResponse annotations, for example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
package com.huongdanjava.springbootspringfox; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiResponse; import io.swagger.annotations.ApiResponses; @RestController @RequestMapping(value = "/student") public class StudentController { @GetMapping(value = "findById") @ApiOperation(value = "Find student by id") @ApiResponses(value = { @ApiResponse(code = 200, message = "Success", response = String.class), @ApiResponse(code = 422, message = "Student not found"), @ApiResponse(code = 417, message = "Exception failed") }) public String findById(int id) { return "Khanh"; } } |
Result:
and
Priyanshu Neema
How to change this path http://localhost:8080/api-docs