Consolidate API specs from smartem-decisions #8
Description
Context
Documentation has been migrated to smartem-devtools SPA. Two API specs remain in smartem-decisions:
- SmartEM API spec - Auto-generated from FastAPI (source of truth is the implementation)
- Athena API spec - Static reference document
Goal
Consolidate API documentation in smartem-devtools while maintaining accuracy.
Options
Option A: Reference from source
- Keep SmartEM API spec generation in smartem-decisions
- Move Athena API spec to devtools
- devtools docs link to/fetch SmartEM spec from smartem-decisions
Pros: Simple, no sync needed for SmartEM spec
Cons: Docs split across repos
Option B: CI-based sync (Recommended)
- smartem-decisions CI exports generated OpenAPI spec as artifact
- smartem-devtools CI pulls artifact and includes in docs build
- Athena spec moves directly to devtools
Pros: All docs consolidated, automated sync, source of truth preserved
Cons: CI dependency between repos
Option C: Manual sync with lint check
- Copy both specs to devtools
- CI check in smartem-decisions compares generated spec against devtools copy
- Fails if diverged, prompting manual sync
Pros: Simple setup
Cons: Manual intervention required, risk of drift
Recommendation
Option B provides the best balance - consolidates documentation while preserving the source of truth in smartem-decisions through automation.
Related
- smartem-decisions docs cleanup pending this decision
- Project board: https://github.com/orgs/DiamondLightSource/projects/51