OpenAPI

The documentation of the API (at least the backend template for now) follows the OpenAPI specification. The OpenAPI definition is generated by scanning the Spring @Controller's, which serve as the Single Source of Truth. Thus, the documentation of the API is not saved anywhere permanent inside the codebase and generated on-the-fly only.

The next sections provide an overview how the documentation is integrated and explains the usage.

Available documentation endpoints

The OpenAPI documentation is exposed via two endpoints explained below. Both endpoints will be dynamically updated based on the current annotations and Javadoc present in the @Controller code.

Swagger UI

The Swagger UI provides a web-based interface for exploring and testing the documented API. It is automatically available when using springdoc-openapi-starter-webmvc-ui (which is included in the backend template by default) and can be accessed via the following path:

• /swagger-ui/index.html or
• /swagger-ui (shortform)

This endpoint renders the OpenAPI specification in a user-friendly format and allows direct interaction with all available endpoints.

OpenAPI

The raw OpenAPI specification is served as machine-readable .json and .yaml. It can be retrieved from the following standard paths:

• /v3/api-docs (.json) or
• /v3/api-docs.yaml

These endpoints are normally used for client generation, validation or export of the documentation as this is a standardized format for any OpenAPI generator.

Generating API definition

The current API definition can be generated locally as a .yaml file using the Springdoc Maven plugin.

This is useful for different use-cases e.g.:

• OpenAPI-based client generation
• External documentation processing

The export is performed via the following command:

mvn springdoc-openapi:generate

Information

The backend component must be running during this process. The plugin fetches the OpenAPI definition from the running instance via its /v3/api-docs endpoint.

The OpenAPI .yaml file will be saved to the project's target directory with the name of the Maven artifact itself ({artifact-name}.yaml).

IMPORTANT

Changing the output file location or name via plugin configuration is highly discouraged, as other processes (e.g., client generation) might depend on the default.

Documenting endpoints

Currently, there are two ways to add documentation to an endpoint. Those will be further explained below.

Information

We suggest to combine both mechanisms and provide the basic API documentation via Javadoc enriched via advanced metadata where necessary using annotations.

Javadoc (suggested)

Documenting the various endpoints via Javadoc is the more intuitive way and has other benefits for generation of documentation and IDE support. By documenting a method with basic Javadoc the generator will supply information directly to the OpenAPI documentation.

Information

Using Javadoc only allows the documentation of a description, the variables used for the request and the return value. Examples for a request are automatically created with default values.

More information about the Javadoc integration can be found in the official Springdoc documentation.

Example:

/**
 * This text is used as a description for the following request.
 * @param someId describes the path variable used for this request.
 * @return explains the return value of the request.
 */
@GetMapping("{someId}")
@ResponseStatus(HttpStatus.OK)
public SomeEntity getEndpoint(@PathVariable("someId") final UUID someId) {
    return service.doSth(someId);
}

Swagger Annotations

In addition to Javadoc, it's possible to document endpoints using OpenAPI-specific annotations. This approach offers much finer control over the generated documentation, allowing for custom examples, detailed descriptions, response codes, parameter specifications, and security requirements.

Annotation-based documentation is especially useful when more structured metadata is needed, such as for standardized response objects or complex request examples.

A full list of available annotations can be found in the Swagger OpenAPI documentation

Example:

@Operation(
    summary = "Your summary here",
    description = "This text is used as a description for the following request.",
    parameters = {
        @Parameter(
            name = "someId",
            description = "someId for an entity",
            required = true,
            in = ParameterIn.PATH,
            example = "a81bc81b-dead-4e5d-abff-90865d1e13b1"
        )
    }
)
@ApiResponses(value = {
    @ApiResponse(
        responseCode = "200",
        description = "Entity for someId was found"
    ),
    @ApiResponse(responseCode = "404", description = "SomeEntity not found"),
})
@GetMapping("{someId}")
@ResponseStatus(HttpStatus.OK)
public SomeEntity getEndpoint(@PathVariable("someId") final UUID someId) {
  return service.doSth(someId);
}