I started my first programming job at t-matix in the backend team working on the reporting part of the IoT platform. It is a big, ongoing project. Among the many challenges I faced as a trainee developer was understanding the new codebase. One of the first tasks I was assigned to was preparing the documentation for the exposed REST endpoints by using Swagger. That way it could easily be shared among t-matix employees when required. I saw this task as an opportunity to gain better understanding of the reporting project and thus start contributing. So, where else to begin but googling what Swagger is first.

What is Swagger?

Swagger is a framework used for generating RESTful API documentation. It can also be used by various tools to automate other API-related processes. It is a specification which is independent of the programming language and readable by both computers and humans, and includes automated documentation, code generation (into many programming languages) and test-case generation. Swagger is used together with a set of open-source software tools. Among these tools, the popular one for Spring Boot applications is Springfox.

Starting with Swagger

After I got the basic understanding of Swagger, it was time to apply Springfox implementation of the Swagger specification on the reporting part of the IoT platform. Since the project is developed with a microservice architecture approach, I started by trying out Swagger on one of the services. In order to bring it in, I needed to include it into the Maven project, by adding dependency to Springfox in the pom.xml file. Configuration of Swagger was also required, which mainly centered around the Docket bean, which provides a way to control the endpoints exposed by Swagger.

Describing REST endpoints

Finally, I was able to describe the REST endpoints by using Swagger annotations. I declared what the exposed REST requests do and described their input parameters as well as outputs provided after executing the requests. It was decided to place the annotations in the REST interfaces rather than classes implementing these interfaces because the code would be easier to read. The following annotations were used:

@ApiOperation – describes an operation or typically a HTTP method against a specific path;

@ApiParam – describes a method parameter; it can specify name, type, description (value), and example;

@ApiResponse – describes a possible response of an operation, and can be used to describe possible success and error codes from the REST API call; it should be used within the @ApiResponses.

Most of the REST endpoints receive parameters and/or return responses in the form of DTO (Data Transfer Object). The DTO model properties are described using @ApiModelProperty. This annotation allows the manipulation of Swagger-specific definitions such as description (value), name, data type, example values, and allowed values for the model properties.

After running the service with implemented Swagger annotations, the web page is generated. This intuitive Swagger UI representation contains a list of all controllers defined in the RESTful service. Clicking on any of them will list all available HTTP methods.

Java classes not supported by Swagger

In the process of implementing springfox-swagger v 3.0.0, I encountered a few problems worth mentioning. If Swagger is implemented over the REST methods containing java classes not supported by Swagger, for example LocalDate or Instant, the log may produce an error such as:

ReferenceModelSpecificationToPropertyConverter – Unable to find a model that matches key ModelKey{qualifiedModelName=ModelName{namespace=’java.time’, name=’LocalDate’}, viewDiscriminator=null, validationGroupDiscriminators=[], isResponse=true}

This problem can be solved by providing model substitution rules for the Docket bean in the Swagger configuration class:

Furthermore, the fields of certain java class types such as TimeZone, could not be accurately represented with Swagger UI. In such cases, changing the dataType of the field was helpful.

Customisation of Swagger UI

My task also included t-matix branding of the Swagger interface. Even though Springfox library does not support this option, customization of Swagger UI could easily be done by copying html/css files from the springfox github repository and changing the desired header and body values.

Testing of the REST API using the Swagger UI

After Swagger was implemented over all services in the reporting project containing exposed REST endpoints, these services were deployed on the testing environment to test HTTP request execution using the Swagger interface.

Conclusion

API documentation should be informative, clear and easy to follow. Due to its ability to be synchronized with the codebase and simultaneously describe changes in the API, using Swagger is a good way to automate the documenting process and save time. On top of that, Swagger can easily be used as an extra tool for API testing and bug fixing.