Keeping OpenAPI DRY

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:

@Operation(summary = "For a given accountId, return a list of orders.")

@ApiResponses(value = { 

  @ApiResponse(responseCode = "200", description = "ok"), 

  @ApiResponse(responseCode = "400", description = "request could not be processed"),

  @ApiResponse(responseCode = "401", description = "user account is not valid", content = @Content()),

  @ApiResponse(responseCode = "403", description = "user does not have access to perform this request", content = @Content())

})

@GetMapping(value = "account/{accountId}/orders")

public ResponseEntity<List<Order>> getOrders(@PathVariable Long accountId) {

    try {

        return new ResponseEntity<>(orderService.getOrders(accountId), HttpStatus.OK);

    } catch (OrderException e) {

       return new ResponseEntity<>(HttpStatus.BAD_REQUEST);

    }

}

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:

xxxxxxxxxx

@Retention(RetentionPolicy.RUNTIME)

@Target(ElementType.METHOD)

@ApiResponses(value = {

  @ApiResponse(responseCode = Constants.UNAUTHORIZED, description = "request could not be processed", content = @Content()),

  @ApiResponse(responseCode = Constants.FORBIDDEN, description = "user account is not valid", content = @Content())

})

public @interface ApiAuthResponses { }

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:

xxxxxxxxxx

public static final String OK = "200";

public static final String CREATED = "201";

public static final String ACCEPTED = "202";

public static final String NO_CONTENT = "204";

public static final String BAD_REQUEST = "400";

public static final String UNAUTHORIZED = "401";

public static final String FORBIDDEN = "403";

public static final String NOT_FOUND = "404";

public static final String METHOD_NOT_ALLOWED = "405";

public static final String CONFLICT = "409";

public static final String UNPROCESSABLE = "422";

public static final String INTERNAL_SERVER_ERROR = "500";

public static final String ACCEPTED_TEXT = "accepted";

public static final String CREATED_TEXT = "created";

public static final String NO_CONTENT_TEXT = "no content";

public static final String OK_TEXT = "ok";

The Updated Controller

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

xxxxxxxxxx

@Operation(summary = "For a given accountId, return a list of orders.")

@ApiResponses(value = { 

  @ApiResponse(responseCode = Constants.OK, description = Constants.OK_TEXT), 

  @ApiResponse(responseCode = Constants.BAD_REQUEST, description = "request could not be processed")

})

@ApiAuthReponses

@GetMapping(value = "account/{accountId}/orders")

public ResponseEntity<List<Order>> getOrders(@PathVariable Long accountId) {

    try {

        return new ResponseEntity<>(orderService.getOrders(accountId), HttpStatus.OK);

    } catch (OrderException e) {

       return new ResponseEntity<>(HttpStatus.BAD_REQUEST);

    }

}

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

DevOps and the DRY Principle