Documenting your RESTful API with Springfox for Swagger in Spring Boot

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 document in Spring. In this tutorial, let’s find out how to create a RESTful API document using Springfox for Swagger in Spring Boot.

First of all, we need a Spring Boot project as an example:

Documenting your RESTful API with Springfox for Swagger in Spring Boot

I now use Spring Boot version 1.5.10.RELEASE with Spring Boot project created using Spring Initializr Web. You can read more about Spring Initializr Web here.

To work with Springfox, we need to add its dependency:

Suppose I now have a controller that defines an API for managing student information simply as follows:

To be able to create the RESTful API document for this StudentController, the first thing we need to do is to add the Springfox @EnableSwagger2 annotation to the SpringBootSwaggerApplication class definition:

Adding this to Springfox knows we need to create a RESTful API document using Swagger specification 2.0 in our application.

Next we need to define a Bean of the Springfox Docket class in the Spring container:

Here, I created the Bean of the Docket class with support for Swagger specification 2.0. A Springfox Docket is a primary object used to configure the creation of RESTful API documentation in Springfox. It provides us with the necessary methods so that we can create a RESTful API document.

The select() method returns the ApiSelectorBuilder object, which allows us to use the ApiSelectorBuilder object with the apis() and paths() methods to filter which controllers, which methods to use, to create a RESTful API document.

As you can see in the path() method, we used the PathSelectors object with the regex() method to filter the creation of the RESTful document only for the “/ student” URL request.

Now, if you run this Spring Boot application and request to the http://localhost:8080/swagger-ui.html URL, you will see the following result:

Documenting your RESTful API with Springfox for Swagger in Spring Boot

As you can see, here Springfox has created a document with information about our StudentController. If you click on GET request “/student/findById” then you will see the results as follows:

Documenting your RESTful API with Springfox for Swagger in Spring Boot

As you can see, Springfox has used a number of default values to create our Student Controller document according to Swagger standards.

In addition to the default values that Springfox has generated, Springfox also allows us to customize our RESTful API document.

We may add some additional information about our APIs, such as the following contact information:

In the above example, I have added some information such as title, description and contact for our document.

Result:

Documenting your RESTful API with Springfox for Swagger in Spring Boot

We can also customize the API documentation by adding some description about it, the data returned. We do this by modifying StudentController, for example:

Result:

Documenting your RESTful API with Springfox for Swagger in Spring Boot

 

Đánh giá bài viết
Chia sẽ bài viết này ...Share on Facebook
Facebook
0Tweet about this on Twitter
Twitter
Share on LinkedIn
Linkedin

Add Comment