Changes
Replace the current OpenAPI documentation generation flow that starts the full Docker Compose stack and harvests service endpoints.
Current files involved:
make/gen.mkdocs/.openapi/openapi-generate.shdocs/.openapi/openapi-merge.json
The new flow should generate per-service OpenAPI specs without starting the full runtime stack, then merge them once.
Additional notes
Current issues:
- Starts the full stack just to generate docs.
- Depends on Docker networking, container names, health checks, and runtime config.
- Makes doc generation slow and fragile.
- Runs openapi-merge-cli twice.
- Harvests dashboard-service, but openapi-merge.json does not include api-dashboard-service.yaml.
- Merge inputs are implicit/generated, not clearly owned by service-specific generation steps.
Suggested direction:
- Spring Boot services: generate specs via Maven/Spring test context, MockMvc, or springdoc-compatible build step.
- Flask services: generate specs through Flask test client or app import, without Compose.
- Merge generated specs once after all service specs exist.
- Keep Compose-based harvesting only as an optional smoke test if still useful.
Assumptions
The OpenAPI output does not need a fully running production-like stack and can be generated from service code/configuration in isolation.
Acceptance Criteria
- OpenAPI docs can be generated without running docker compose up.
- Each service has a deterministic generation step for its OpenAPI spec.
- openapi-merge-cli is executed only once.
- openapi-merge.json matches the actually generated service specs.
- make gen-openapi-doc still produces docs/.openapi/api.yaml and docs/api/rest.md.
- The generated merged API documentation is equivalent or intentionally updated compared to the current output.
Risks? (optional)
Some OpenAPI fields may currently depend on runtime environment variables. If so, define stable documentation defaults for generation instead of depending on the Compose runtime.
Changes
Replace the current OpenAPI documentation generation flow that starts the full Docker Compose stack and harvests service endpoints.
Current files involved:
make/gen.mkdocs/.openapi/openapi-generate.shdocs/.openapi/openapi-merge.jsonThe new flow should generate per-service OpenAPI specs without starting the full runtime stack, then merge them once.
Additional notes
Current issues:
Suggested direction:
Assumptions
The OpenAPI output does not need a fully running production-like stack and can be generated from service code/configuration in isolation.
Acceptance Criteria
Risks? (optional)
Some OpenAPI fields may currently depend on runtime environment variables. If so, define stable documentation defaults for generation instead of depending on the Compose runtime.