Consolidate API specs from smartem-decisions

[vredchenko]

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

[vredchenko]

Superseded by ADR 0020 (OpenAPI spec pipeline) / PR #222, which automates the spec sync.