Skip to content

Project Catalyst - Catalyst Voices

0014 OpenAPI First and Code Generation

input-output-hk/catalyst-voices

0014 OpenAPI First and Code Generation

Author:: Assistant
Created:: 2025-10-29
Status:: Accepted
Tags:: codegen openapi poem swagger-dart

Context¶

We maintain a Rust backend and Flutter clients that must evolve together without drift. Manual client implementations are error prone and slow down iteration.

Assumptions¶

Backend can produce OpenAPI artifacts during builds.
Flutter code can be generated reliably from OpenAPI specs.

Decision¶

Adopt an OpenAPI first workflow using poem_openapi on the backend and swagger_dart_code_generator on the client. Package artifacts via Earthly and integrate generated client code into the repositories layer.

Rationale¶

Typed contracts and generated clients reduce integration bugs and speed up feature delivery. OpenAPI artifacts also enable documentation and automated testing.

Implementation Guidelines¶

Define routes and schemas with poem_openapi annotations.
Publish OpenAPI artifacts from backend Earthly targets.
Generate Dart clients into the internal repositories package and review diffs.

Risks¶

Generator limitations or breaking changes can block upgrades. Specs must remain accurate to avoid client breakages.

Consequences¶

Faster consistent client integrations. Single source of truth for API contracts and documentation.

More Information¶