census-rm-case-api

Overview

The service relies on, and makes no changes to the case schema maintained by census-rm-ddl.

📚 API Documentation

For Integration Teams (Contact Centre, etc.)

→ See API_DOCUMENTATION.md for complete information on accessing and using the OpenAPI specifications.

The Case API automatically generates OpenAPI documentation from the codebase. Three formats are published on every commit:

• openapi.json - Machine-readable API contract (source of truth, committed in api-docs/) for API gateways and client code generation
• openapi.md - Markdown documentation (derived from openapi.json)
• openapi.html - Interactive ReDoc explorer (derived from openapi.json)

All artifacts are available in the GitHub Actions CI/CD pipeline under rm-case-api-openapi-specs artifact.

For Response Management Team Developers

• OpenAPI specs are auto-generated from annotated endpoints (no manual maintenance)
• Specs are generated during integration tests via DocumentationGeneratorIT
• CI fails if committed api-docs/openapi.json is out-of-sync with generated output
• To enhance documentation, add Swagger annotations (see API_DOCUMENTATION.md for examples)
• To generate locally: run make build and open api-docs/openapi.html

---

Building Open API Documentation

OpenAPI documentation is generated by the DocumentationGeneratorIT integration test, not by a Maven plugin. The test uses npx to run widdershins and ReDoc, so a global widdershins install is not required.

Prerequisite: Node.js 22+ is required locally so npx can run widdershins and @redocly/cli.

The api-docs/ directory is created during the test run, so developers do not need to create it manually.

Note: This is automatically handled in CI/CD via GitHub Actions. You only need it locally if running make build manually.

OpenAPI Specifications

The OpenAPI v3 spec is generated automatically by integration tests.

Source of truth: committed api-docs/openapi.json in this repository.

openapi.md and openapi.html are generated from that JSON and published as GitHub Actions artifacts for easier consumption.

Local (after running make build):

• Machine-readable: api-docs/openapi.json
• Human-readable: api-docs/openapi.md
• Interactive browser: api-docs/openapi.html

---

Configuration

By default settings in src/main/resources/application.yml are used to configure census-rm-case-api.

For production the configuration is overridden by the K8S apply script

How to run

The service requires several other services to be running, started from census-rm-docker-dev.

How to debug census-rm-case-api locally

Running as a docker image

• Start census-rm-docker-dev services with the following line in section caseapi | environment in rm-services.yml:

  JAVA_OPTS=-Xmx512m -Xdebug -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8162

• In IntelliJ, create a "Remote" configuration, set port = 8162 and run in debug mode.

Running inside IntelliJ

• Stop the census-rm-case-api service if already running
• In IntelliJ, create a SpringBoot Run configuration and run in debug mode

Testing

In isolation

From the project root directory, run "mvn clean install", this -

• Runs all unit tests
• Builds a new local docker image
• Brings up this image with all required services and runs all integration tests

With Acceptance Tests

• From census-rm-acceptance-tests, run "make test"