alex
e7819bfc82
- Add docker-compose.yml with postgres, redis, api, and web services - Add multi-stage Dockerfile for API (Python 3.11) - Add multi-stage Dockerfile for web (Node.js 20 + nginx) - Add Makefile with common development commands - Add .env.example with all required environment variables - Add placeholder pyproject.toml and package.json for builds - Configure health checks for all services - Setup persistent volumes for postgres, redis, and repos - Run services as non-root users
95 lines
2.2 KiB
Markdown
95 lines
2.2 KiB
Markdown
# API Documentation Specification
|
|
|
|
## Purpose
|
|
|
|
Provide comprehensive API documentation and health monitoring endpoints.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: OpenAPI/Swagger Documentation
|
|
|
|
The system SHALL auto-generate API documentation.
|
|
|
|
#### Scenario: API docs access
|
|
- GIVEN the running API server
|
|
- WHEN visiting `/docs`
|
|
- THEN Swagger UI displays:
|
|
- All available endpoints
|
|
- Request/response schemas
|
|
- Authentication requirements
|
|
- Example requests and responses
|
|
|
|
### Requirement: Health Check Endpoints
|
|
|
|
The system SHALL provide health monitoring endpoints.
|
|
|
|
#### Scenario: General health check
|
|
- GIVEN the running API server
|
|
- WHEN visiting `/health`
|
|
- THEN it returns:
|
|
- Overall service status
|
|
- Database connectivity status
|
|
- Redis connectivity status
|
|
- Disk space status
|
|
- Uptime information
|
|
|
|
#### Scenario: Database health check
|
|
- GIVEN the running API server
|
|
- WHEN visiting `/health/db`
|
|
- THEN it returns:
|
|
- Database connection status
|
|
- Response time
|
|
- Connection pool status
|
|
|
|
### Requirement: API Setup Documentation
|
|
|
|
The system SHALL document API setup and configuration.
|
|
|
|
#### Scenario: Developer onboarding
|
|
- GIVEN a new developer
|
|
- WHEN they read `apps/api/README.md`
|
|
- THEN they find:
|
|
- Setup instructions
|
|
- Environment variables
|
|
- Running tests
|
|
- Common commands
|
|
- Architecture overview
|
|
|
|
### Requirement: Architecture Decision Records
|
|
|
|
The system SHALL document significant architectural decisions.
|
|
|
|
#### Scenario: Auth decision record
|
|
- GIVEN the codebase
|
|
- THEN an ADR SHALL exist documenting:
|
|
- Why httpOnly cookies were chosen
|
|
- Alternatives considered
|
|
- Trade-offs and risks
|
|
- Decision date and participants
|
|
|
|
### Requirement: Endpoint Documentation
|
|
|
|
The system SHALL document all API endpoints.
|
|
|
|
#### Scenario: Endpoint coverage
|
|
- GIVEN the API codebase
|
|
- THEN every endpoint SHALL have:
|
|
- Pydantic request/response models
|
|
- Docstrings with descriptions
|
|
- Response status codes
|
|
- Authentication requirements
|
|
|
|
## Dependencies
|
|
|
|
- FastAPI (auto-generates OpenAPI)
|
|
- Pydantic v2
|
|
|
|
## Quality Gates
|
|
|
|
- `/docs` endpoint loads successfully
|
|
- `/health` returns 200 with valid JSON
|
|
- `/health/db` returns database status
|
|
- `pytest` must pass
|
|
- `mypy .` must pass
|
|
- `ruff check .` must pass
|