README.adoc

Spring Boot: WebMvc

API Implementations

This showcase contains a simple API for managing books of a library. The API was implemented twice:

1. /default-api/books/** returns application/json data.

   • @RestController implementation

   • @WebMvcTest technology integration tests

2. /hateoas-api/books/** returns application/hal+json data using Spring HATEOAS.

   • @RestController implementation

   • @WebMvcTest technology integration tests

Error Handling

Spring 6 / Spring Boot 3 introduced optional support for RFC-7807 problem details. This can be activated by simply setting spring.mvc.problemdetails.enabled to true. Doing so will replace (most of) the legacy error handling with a @ControllerAdvice that converts any exceptions into ProblemDetail data.

To make this more interesting for the usecase, we override the default to include an optional trace ID for each problem response. We provide a CustomResponseEntityExceptionHandler component to replace Spring’s default ProblemDetailsExceptionHandler. There we just override a single method responsible for packaging the final result of the handler into a ResponseEntity.

That everything works as we intend, is tested on several levels:

1. Inside the tests for the default and HATEOAS controllers where we test the not found cases.

2. As part of the application smoke tests to check that the general configuration works.

Request/Response Logging

The showcase implements basic request / response logging using Zalando’s Logbook library. This just requires us to add a couple of dependencies to our build file and set some application properties.

To take full advantage of the logged request / response data, we also add a custom Logback configuration to enable JSON logging if the json-logging profile is activated. With that, log sinks (e.g. ELK stack) can easily extract the request’s / response’s properties and make them searchable.

That all of this works as we want it to, is checked as part of the application smoke tests.

Spring REST Docs

The showcase generates API documentation from the already existing tests using Spring REST Docs. To do so we have a AsciiDoc file containing our static parts and include statements to so-called snippets. These snippets are the parts generated by our tests.

To generate a snippet, we just activate Spring REST docs inside our tests using the @AutoConfigureRestDocs annotation and adding an extra step to relevant tests to trigger the documentation.

Note	To keep the example simple, we do not use all the available features. As an example, we do not document parameters or request / response bodies. Although we might do so in the future.

To get the generated documentation as an HTML file we add the org.asciidoctor.jvm.convert plugin to our build file and link it into our general workflow.