We often implement web applications with a React frontend and one of a large pool of backend frameworks/technologies. These include Micronaut, .NET Framework, Javalin, Flask, Eclipse Jetty among others.
A documentation of the API that allows calling the endpoints can be very helpful even during development to illustrate the API usage. OpenAPI and implementations like Swagger and Swashbuckle fulfill this task quite well.
While many of the backend frameworks support documenting and calling the API using Swagger-UI out-of-the-box or using plugins some frameworks like Undertow do not have direct support for it. Nevertheless, it is relatively easy to add an OpenAPI documentation with a web interface to almost any backend. We demonstrate the setup here using Undertow because it is used in some of our projects.
Adding dependencies and build config
Since we mostly use Gradle for our JVM-based backends we will highlight the additions to build.gradle to make to generate the OpenAPI definition. It consists of the following steps:
- Adding the Swagger gradle plugin
- Adding dependencies for the required annotations
- Configuring the resolve-task of the gradle plugin
Here is an example exerpt of our build.gradle:
plugins {
id 'java'
id 'application'
// ...
id "io.swagger.core.v3.swagger-gradle-plugin" version "2.2.20"
}
dependencies {
// ...
implementation 'io.undertow:undertow-core:2.3.12.Final'
implementation 'io.undertow:undertow-servlet:2.3.12.Final'
implementation 'io.swagger.core.v3:swagger-annotations:2.2.20'
implementation 'org.jboss.resteasy:jaxrs-api:3.0.12.Final'
}
resolve {
outputFileName = 'demo-server'
outputFormat = 'JSON'
prettyPrint = 'TRUE'
classpath = sourceSets.main.runtimeClasspath
resourcePackages = ['com.schneide.demo.server', 'com.schneide.demo.server.api']
outputDir = layout.buildDirectory.dir('resources/main/swagger').get().asFile
}
Adding the annotations
We need to add some annotations to our code so that the OpenAPI JSON (or YAML) file will be generated.
The API root class looks like below:
@OpenAPIDefinition(info =
@Info(
title = "Demo Server Web-API",
version = "0.11",
description = "REST API for the demo web application..",
contact = @Contact(
url = "https://www.softwareschneiderei.de",
name = "Softwareschneiderei GmbH",
email = "kontakt@softwareschneiderei.de")
)
)
public class ApiHandler {
public ApiHandler() {
super();
}
/**
* Connect our handlers
*/
public RoutingHandler createApiHandler() {
final RoutingHandler api = new RoutingHandler();
api.get("/demo", new DemoHandler());
// ...
return api;
}
}
We also refactored our handlers to separate the business api and the Undertow handler interface methods to generate a expressive API.
The result looks something like this:
@Path("/api/demo")
public class DemoHandler implements HttpHandler {
public DemoHandler() {
super();
}
@Override
public void handleRequest(HttpServerExchange exchange) throws Exception {
exchange.getResponseHeaders().put(Headers.CONTENT_TYPE, "application/json");
final Map<String, Deque<String>> params = exchange.getQueryParameters();
final int month = Integer.parseInt(params.get("month").getFirst());
final int year = Integer.parseInt(params.get("year").getFirst());
exchange.getResponseSender().send(new Gson().toJson(getDaysIn(year, month)));
}
@GET
@Operation(
summary = "Get number of days in the given month and year",
responses = {
@ApiResponse(
responseCode = "200",
description = "A number of days in the given month and year",
content = @Content(mediaType = "application/json",
schema = @Schema(implementation = Integer.class)
)
)
}
)
public Integer getDaysIn(@QueryParam("year") int year, @QueryParam("year") int month) {
return YearMonth.of(year, month).lengthOfMonth();
}
}
When running the resolve task all of the above results in a OpenAPI definition file in build/resources/main/swagger/demo-server.json.
Swagger-UI for the API definition
Now that we have this API definition we can use it to generate clients and – more important to us – generate a web UI documenting the API and allowing to execute and demo the functionality. For this we simply download the Swagger-UI distribution and place the contents of the dist/ folder in src/main/resources/swagger-ui. We then have to let Undertow serve definition and UI like so:
class DemoServer {
public DemoServer() {
final GracefulShutdownHandler rootHandler = gracefulShutdown(createHandler());
Undertow.builder().addHttpListener(8080, "localhost").setHandler(rootHandler).build().start();
}
private HttpHandler createHandler() {
return path()
.addPrefixPath("/api", new ApiHandler().createApiHandler())
.addPrefixPath("/swagger-ui", resource(new ClassPathResourceManager(getClass().getClassLoader(), "swagger-ui/"))
.setWelcomeFiles("index.html"))
.addPrefixPath("/swagger", resource(new ClassPathResourceManager(getClass().getClassLoader(), "swagger/")));
}
}
Note: I tried using the swagger-ui webjar but was unable to configure the location (the URL) of my OpenAPI definition file. Therefore I used the plain swagger-ui download instead.
Wrapping it up
We have to do some setup work and potentially some refactorings to provide a meaninful API documentation for our backend. After this work it is mostly adding some Annotations to methods and types used in your web API.
Schneide Blog 