💡 Published OpenAPI 3.1 Specification & Interactive Documentation (Redocly/Swagger)

[don-petry]

Context & Objective

As broodminder-data evolves to make BroodMinder data accessible across various ecosystems, we will publish, validate, and maintain a formal OpenAPI 3.1 Specification documenting the BroodMinder External User API, accompanied by interactive web documentation and contract validation, directly modeling the architecture established in empower-personal-dashboard.

Currently, we maintain an initial reverse-engineered YAML spec in openapi/broodminder-openapi.yaml. We want to make this specification a first-class, published public artifact with automated CI validation, interactive documentation rendering, and upstream drift detection.

Scope & Architecture

1. Two-Tier Specification Architecture:

   • Tier 1 (Upstream Wire Protocol): Documents the live External User API endpoints (/user/metadata/apiaries, /user/metadata/hives, /user/metadata/devices, /user/devices/{device_id}/readings, /user/hives/{hive_id}/notes), authentication headers (x-api-key), error response codes (including non-standard 412 auth responses and 429 rate limit behavior), and raw JSON array structures.
   • Tier 2 (Canonical Domain Schemas): Defines normalized schemas for apiaries, hives, positions, sensor telemetry (temperature, humidity, scale weight, swarm indicators, audio, radar), and inspection notes.

2. Published Interactive Documentation:

   • Deploy interactive documentation hosted via GitHub Pages using Redocly and Swagger UI.
   • Provide searchable endpoints, parameter descriptions, schema models, and copy-paste code snippets (cURL, Python, TypeScript).
   • Maintain a root-level symlink openapi.yaml and redocly.yaml configuration for developer ergonomics.

3. Automated Linting & Contract Verification:

   • Run @redocly/cli lint in GitHub Actions CI to ensure strict compliance with OpenAPI 3.1 standards.
   • Automated contract tests (extending tests/test_contract.py) comparing live API responses with declared OpenAPI schemas, automatically detecting when upstream BroodMinder backend services change or add fields.

Proposed Developer Experience

# Lint OpenAPI specification locally
npx @redocly/cli lint openapi/broodminder-openapi.yaml

# Launch interactive local documentation preview
npx @redocly/cli preview-docs openapi/broodminder-openapi.yaml

# Run live contract tests against the specification
pytest tests/test_contract.py -m live

Acceptance Criteria

• Published OpenAPI 3.1 YAML and JSON artifacts accessible via GitHub Pages / repository root.
• Automated Redocly linting in CI workflow.
• Complete schema coverage for all observed endpoints and sensor metric payloads.
• Integration with SDK code generation and documentation sites.