Keeping OpenAPI DRY
Keeping OpenAPI DRY
See an example of how your OpenAPI documentation can provide the necessary information without introducing duplication.
Join the DZone community and get the full member experience.Join For Free
I really enjoy API development. As someone who enjoys writing, I also enjoy providing solid documentation for consumers of my APIs to utilize. When my APIs are used by teams across the United States and other countries it becomes important to provide reliable and detailed information. The same is true for public APIs when the consumer is simply not known.
However, I really am not a fan of repetition in my code...and that includes API documentation.
When our team ran into an issue with SpringFox and SpringBoot version 2.2.x, I decided to convert from using SpringFox to springdoc-openapi for our API documentation. Having seen a lot of repeated items in the SpringFox annotations from one controller method to another, I decided to figure out how to employ the DRY (don't repeat yourself) principle to the OpenAPI documentation, which we would serve up using Swagger.
You may also like: Software Design Principles DRY and KISS
A Common Example
Consider the following controller example:
There are some annotations in use that drive the population of data for the Swagger UI.
You may have noticed that the controller throws a BAD_REQUEST response, but Swagger accounts for UNAUTHORIZED and FORBIDDEN responses as well. These will be thrown from a Security Interceptor. If you want to see an example, simply review the following article I published last month:
While the information in the example above will produce very nice documentation, after a couple of APIs, it will be easy to realize there is a lot of duplication of annotation text involved. This would be not so DRY, if you ask me.
There has to be a better way to do this.
Since Java version 5, developers have been able to create and use annotations to make their life easier. So, certainly there has to be a way to use an annotation to keep from repeating myself on every controller that I am exposing to Swagger.
Turns out, it was quite simple. Consider the following example for the UNAUTHORIZED and FORBIDDEN documentation:
Now, I can simply include @ApiAuthResponses to my controller to include these two responses. What this means is that the content is in one location, so if we decide to change the text, the changes only have to be made one time.
Also, I went ahead and established constants for all of our basic responseCode and description values too:
The Updated Controller
With the interface and constants in place, the updated controller appears as follows:
Now, the documentation for the getOrders() URI contains only information that is applicable for this controller method. Common responseCodes and descriptions were moved to a Constants class. The documentation for common exceptions was pushed into the ApiAuthResponses class.
As a result, my OpenAPI documentation is exactly how I like it...useful and quite DRY.
Have a really great day!
Opinions expressed by DZone contributors are their own.