docs: Create hosted API documentation (OpenAPI/Swagger)

[YaronZaki]

Problem Statement

FastAPI auto-docs are available at the /docs endpoint when the application is running, but no static/hosted version exists for external consumers or partners. No OpenAPI spec is published to a stable URL.

Evidence

• FastAPI auto-generated docs available at /docs (only when app is running)
• No static OpenAPI JSON published anywhere
• No hosted documentation site (GitHub Pages, Redoc, Scalar)

Impact

Medium — developer experience. External integrators cannot browse the API without running the application locally. No versioned API documentation for partners. API changes are not documented in an accessible changelog.

Proposed Solution

Generate static OpenAPI spec from FastAPI using app.openapi(). Render with Redoc or Scalar and publish to GitHub Pages via a CI step. Add API doc generation to CD pipeline.

Acceptance Criteria

• Static OpenAPI JSON generated from FastAPI app.openapi()
• API docs hosted on GitHub Pages or equivalent
• CI step generates and publishes docs on merge to main
• Documentation includes all public endpoints with descriptions

File Map

• docs/api/openapi.json — New: generated OpenAPI spec
• docs/api/index.html — New: Redoc or Scalar renderer page
• .github/workflows/cd.yml — add API doc generation step

Testing Strategy

• Manual: Verify hosted docs page loads and displays all endpoints correctly.

Security Considerations

Ensure internal/private endpoints are not exposed in public API docs.

Definition of Done

• Code implemented and peer-reviewed
• Docs published and accessible
• PR linked and merged

---

Labels: documentation
Priority: Medium
Difficulty: Intermediate
Estimated Effort: 2h

[Uche44]

I am a fullstack python developer proficient with fastAPI.

I have built extensive backend systems with fastAPI while documenting and testing with swagger.

I can definitely deliver this.