API Documentation | Identity Service User Guide

Source of truth

The public HTTP contract is maintained in:

src/main/resources/openapi/identity-api.yaml

Change this YAML first when an endpoint, schema, status code, or validation rule changes. Maven then generates the Spring MVC interfaces, API models, and static HTML reference from the same contract.

Ownership rule: edit the YAML and handwritten implementations. Never patch a generated interface, model, MapStruct implementation, or generated HTML report.

Static public API reference

The OpenAPI Generator Maven plugin uses the html2 generator during generate-sources. Local output is written to:

target/openapi-docs/index.html

GitHub Actions publishes that output as the public, runtime-independent API reference:

Open generated OpenAPI documentation

GitHub Pages serves static files only. It does not run Spring Boot or proxy requests to a local backend.

Local Swagger UI

When the application is running, springdoc exposes an interactive local UI at:

http://localhost:8080/api/swagger-ui.html

Open local Swagger UI. The link works only on the machine where Identity Service is running on port 8080.

API versions

Version	Operations	Purpose
`v1`	`POST /api/v1/users` `GET /api/v1/users/{id}` `DELETE /api/v1/users/{id}`	Minimal user creation, retrieval, and soft deletion.
`v2`	`POST /api/v2/users` `GET /api/v2/users/{id}` `PATCH /api/v2/users/{id}`	Profile fields and partial updates while preserving v1.

Errors use RFC 7807 ProblemDetail responses for validation failures, conflicts, and missing resources.

Postman collection

Import the repository collection to exercise the documented operations against a local runtime:

postman/identity-service.postman_collection.json

The collection uses a reusable baseUrl variable and stores the identifier returned by each create request for the following read, update, or delete request.

View the Postman collection on GitHub.

Generated code lifecycle

Output	Location	Generated by
Spring MVC interfaces and API models	`target/generated-sources/openapi`	OpenAPI Generator
MapStruct mapper implementation	`target/generated-sources/annotations`	Java annotation processing
Static OpenAPI HTML	`target/openapi-docs`	OpenAPI Generator `html2`

Regenerate cleanly with:

mvn clean compile

All outputs live under target/, are ignored by Git, and are reproducible from source.