{{announcement.body}}
{{announcement.title}}

Keeping OpenAPI DRY

DZone 's Guide to

Keeping OpenAPI DRY

See an example of how your OpenAPI documentation can provide the necessary information without introducing duplication.

· Web Dev Zone ·
Free Resource

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:

Java


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:

Using @RequestScope With Your API

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.

Enter Annotations

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:

Java


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:

Java


The Updated Controller

With the interface and constants in place, the updated controller appears as follows:

Java


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!

Further Reading

DRYing Up CSS

DevOps and the DRY Principle

Topics:
annotations ,api ,api development ,dry ,open api ,openapi documentation ,spring boot ,swagger ,tutorial ,web dev

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}