ADR 0005: Use Generated OpenAPI and MapStruct

Status

Accepted

Context

The project should document its REST API and avoid repetitive hand-written mapping code at the module boundaries. Both concerns should be automated by Maven so reviewers can verify them from a clean checkout.

Decision

Use springdoc-openapi to expose runtime API documentation. Configure OpenAPI metadata, paths, Swagger UI, and grouping through ecommerce-app/src/main/resources/openapi.yaml. Use a Maven profile named generate-openapi to export openapi.json during the unified CI documentation build. Publish both the raw JSON and a static Swagger UI page on GitHub Pages.

Use MapStruct for REST boundary mapping between application models and HTTP DTOs. Mapper implementations are generated by the Maven compiler plugin during compilation.

Consequences

Benefits:

• generated API documentation stays close to the actual Spring MVC controllers
• OpenAPI configuration lives in a dedicated YAML file instead of hard-coded Java values
• REST DTO mapping is compile-time checked
• generated artifacts are produced by Maven rather than edited manually
• documentation publishing can include Markdown docs, JavaDoc, a static Swagger UI page, and OpenAPI JSON

Trade-offs:

• OpenAPI build-time export requires the application to be running
• the CI documentation build must start PostgreSQL and Redis before exporting the specification
• mapper interfaces are another explicit artifact to maintain at REST boundaries