alex/headquarter
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9f4e9845c0866010630a7b7b8c19eea100fee394
headquarter/openspec/changes/archive/2026-05-19-api-documentation/proposal.md
T
Fusion 94aa88c154 feat: add Sessions Hub page 
- Add Sessions tab to navigation between Dashboard and Projects
- Show active session count badge in navigation
- Create SessionsPage with:
  - Last session section with resume button
  - Active sessions grid with open/stop actions
  - Recent sessions list
  - Create session form with project/repo/tool selectors
- Add last_session_id to user config
- Update UserConfig schemas (backend and frontend)
- Add comprehensive CSS for sessions page

Quality gates: typecheck ✓, lint ✓, build ✓
2026-05-19 23:06:54 +02:00

1.7 KiB
Raw Blame History

API Documentation

Problem

The API lacks comprehensive documentation:

  • No auto-generated OpenAPI/Swagger UI
  • Health endpoint is minimal (only checks database)
  • Missing endpoint documentation and docstrings
  • No API README for developer onboarding
  • No Architecture Decision Records (ADRs)

Solution

Provide comprehensive API documentation:

  1. Auto-generated OpenAPI docs - FastAPI native /docs and /redoc endpoints
  2. Enhanced health checks - /health with full system status, /health/db for database
  3. Endpoint documentation - Proper docstrings, Pydantic models, response codes
  4. API README - Developer onboarding guide
  5. Architecture Decision Records - Document key architectural choices

Key Features

OpenAPI Documentation

  • Interactive Swagger UI at /docs
  • ReDoc at /redoc
  • All endpoints with schemas and examples
  • Authentication documented

Health Monitoring

  • /health - Overall system health (database, disk, uptime)
  • /health/db - Database-specific health check
  • JSON responses with status indicators

Developer Documentation

  • apps/api/README.md - Setup, env vars, testing
  • ADRs in docs/architecture/decisions/
  • Inline code documentation

Benefits

  • Developer onboarding - New devs can understand the API quickly
  • API discoverability - Interactive docs for testing endpoints
  • Health monitoring - Operations can monitor system health
  • Knowledge preservation - ADRs capture why decisions were made

Success Criteria

  • /docs loads Swagger UI with all endpoints
  • /health returns comprehensive health data
  • /health/db returns database status
  • All endpoints have docstrings
  • API README exists with setup instructions
  • At least one ADR exists
Reference in New Issue View Git Blame Copy Permalink