OpenAPI and API-driven Development

We migrate the Artemis server to an API-driven development approach using OpenAPI specifications. This especially helps us with client generation to avoid subtle bugs that are often unnoticed in code reviews.

Currently, the OpenAPI specs are generated for the aiworker, globalsearch, tutorialgroup, hyperion, calendar, and quiz modules. We only support API-driven development for endpoints that are DTO-only and do not return domain objects.

ℹ️

Information:

If you want to make use of the OpenAPI specs, you need to ensure that the endpoint you are working on is a DTO-only endpoint. This means that the endpoint should not return or expect any domain objects, but only Data Transfer Objects (DTOs) or primitives.

Generating OpenAPI Specs and Client Files

When you update a REST endpoint or a DTO, you need to generate a new OpenAPI spec and generate new client files.

Follow these steps to generate the OpenAPI spec and client files:

Generate the OpenAPI Spec

To generate the OpenAPI spec, run the following command in the root directory:

./gradlew generateOpenApiDocs pruneOpenApiSpec -x webapp

This starts a throwaway server, reads its specification and writes an openapi.yaml file to the config/openapi directory. The server uses port 8080 and its SSH server port 7921. If a development server already uses them, add -PopenApiServerPort=<port> and -PopenApiSshPort=<port> to move it.

Generate the Client Files

To generate the client files, run the following command in the root directory:

./gradlew openApiGenerate

This command:

• Prunes the specs file to only include DTO-only endpoints
• Generates the client files based on the OpenAPI spec
• Post-processes generated files: removes unused imports and strips the numeric suffixes that duplicate operation ids leave in method names

The generator returns the full HttpResponse for operations that declare a response header (observeResponseHeaders), so callers can read it.

The generated client files are stored in the src/main/webapp/app/openapi directory.

The Agent API Specification

A second specification lists only the endpoints that a personal access token can call. It is not used to generate a client; it is published at /agent/openapi.yaml for coding agents. It is generated by the same task with -PopenApiGroup=agent and written to documentation/static/agent/openapi.yaml. How to opt an endpoint in, and why a test fails when this file is out of date, is described in Agent Access for Developers.