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 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:

Documenting your RESTful API with Springfox for Swagger in Spring Boot

To work with Springfox for Spring Boot, you just need to add the springfox-boot-starter dependency as follows:

Suppose, I now have a controller that defines an API for managing student information

Documenting your RESTful API with Springfox for Swagger in Spring Boot

simply as follows:

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:

Documenting your RESTful API with Springfox for Swagger in Spring Boot

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:

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:

Documenting your RESTful API with Springfox for Swagger in Spring Boot

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:

Documenting your RESTful API with Springfox for Swagger in Spring Boot

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:

In the example above, I added some information like title, description, and contact to our document.

Result:

Documenting your RESTful API with Springfox for Swagger in Spring Boot

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:

Result:

Documenting your RESTful API with Springfox for Swagger in Spring Boot

and

Documenting your RESTful API with Springfox for Swagger in Spring Boot

Add Comment