238 lines
8.7 KiB
Markdown
238 lines
8.7 KiB
Markdown
# OpenAPI Specification Completion
|
|
|
|
**Date:** 2024-01-13
|
|
**Last Updated:** 2024-01-13
|
|
**Status:** ✅ Complete
|
|
|
|
## Overview
|
|
|
|
The OpenAPI specification for the Attune API has been fully annotated with `utoipa::path` attributes on all route handlers. The API now provides comprehensive, interactive documentation accessible via Swagger UI at `/docs`.
|
|
|
|
## Completed Work
|
|
|
|
### 1. Route Annotations
|
|
|
|
All API endpoints have been annotated with `#[utoipa::path]` attributes including:
|
|
- HTTP method and path
|
|
- Tag categorization
|
|
- Request/response schemas
|
|
- Security requirements (JWT bearer auth where applicable)
|
|
- Parameter descriptions
|
|
- Example values
|
|
|
|
### 2. Endpoints Documented (86 operations across 62 paths)
|
|
|
|
The API has **62 unique paths** with **86 total operations** (HTTP methods). Multiple operations on the same path (e.g., GET, POST, PUT, DELETE) count as separate operations.
|
|
|
|
#### Health Check (4 endpoints)
|
|
- `GET /health` - Basic health check
|
|
- `GET /health/detailed` - Detailed health with database connectivity
|
|
- `GET /health/ready` - Readiness probe
|
|
- `GET /health/live` - Liveness probe
|
|
|
|
#### Authentication (5 endpoints)
|
|
- `POST /auth/login` - User login
|
|
- `POST /auth/register` - User registration
|
|
- `POST /auth/refresh` - Refresh access token
|
|
- `GET /auth/me` - Get current user info
|
|
- `POST /auth/change-password` - Change password
|
|
|
|
#### Packs (7 endpoints)
|
|
- `GET /packs` - List all packs
|
|
- `POST /packs` - Create new pack
|
|
- `GET /packs/{ref}` - Get pack by reference
|
|
- `PUT /packs/{ref}` - Update pack
|
|
- `DELETE /packs/{ref}` - Delete pack
|
|
- `POST /packs/{ref}/sync-workflows` - Sync workflows from pack directory
|
|
- `GET /packs/{ref}/validate-workflows` - Validate workflows in pack directory
|
|
|
|
#### Actions (8 endpoints)
|
|
- `GET /actions` - List all actions
|
|
- `POST /actions` - Create new action
|
|
- `GET /actions/{ref}` - Get action by reference
|
|
- `PUT /actions/{ref}` - Update action
|
|
- `DELETE /actions/{ref}` - Delete action
|
|
- `GET /actions/id/{id}` - Get action by ID
|
|
- `GET /packs/{pack_ref}/actions` - List actions by pack
|
|
- `GET /actions/{ref}/queue-stats` - Get queue statistics for action
|
|
|
|
#### Triggers (10 endpoints)
|
|
- `GET /triggers` - List all triggers
|
|
- `GET /triggers/enabled` - List enabled triggers
|
|
- `POST /triggers` - Create new trigger
|
|
- `GET /triggers/{ref}` - Get trigger by reference
|
|
- `PUT /triggers/{ref}` - Update trigger
|
|
- `DELETE /triggers/{ref}` - Delete trigger
|
|
- `POST /triggers/{ref}/enable` - Enable trigger
|
|
- `POST /triggers/{ref}/disable` - Disable trigger
|
|
- `GET /triggers/id/{id}` - Get trigger by ID
|
|
- `GET /packs/{pack_ref}/triggers` - List triggers by pack
|
|
|
|
#### Sensors (11 endpoints)
|
|
- `GET /sensors` - List all sensors
|
|
- `GET /sensors/enabled` - List enabled sensors
|
|
- `POST /sensors` - Create new sensor
|
|
- `GET /sensors/{ref}` - Get sensor by reference
|
|
- `PUT /sensors/{ref}` - Update sensor
|
|
- `DELETE /sensors/{ref}` - Delete sensor
|
|
- `POST /sensors/{ref}/enable` - Enable sensor
|
|
- `POST /sensors/{ref}/disable` - Disable sensor
|
|
- `GET /sensors/id/{id}` - Get sensor by ID
|
|
- `GET /packs/{pack_ref}/sensors` - List sensors by pack
|
|
- `GET /triggers/{trigger_ref}/sensors` - List sensors by trigger
|
|
|
|
#### Rules (11 endpoints)
|
|
- `GET /rules` - List all rules
|
|
- `GET /rules/enabled` - List enabled rules
|
|
- `POST /rules` - Create new rule
|
|
- `GET /rules/{ref}` - Get rule by reference
|
|
- `PUT /rules/{ref}` - Update rule
|
|
- `DELETE /rules/{ref}` - Delete rule
|
|
- `POST /rules/{ref}/enable` - Enable rule
|
|
- `POST /rules/{ref}/disable` - Disable rule
|
|
- `GET /rules/id/{id}` - Get rule by ID
|
|
- `GET /packs/{pack_ref}/rules` - List rules by pack
|
|
- `GET /actions/{action_ref}/rules` - List rules by action
|
|
- `GET /triggers/{trigger_ref}/rules` - List rules by trigger
|
|
|
|
#### Executions (5 endpoints)
|
|
- `GET /executions` - List all executions (with filters)
|
|
- `GET /executions/{id}` - Get execution by ID
|
|
- `GET /executions/stats` - Get execution statistics
|
|
- `GET /executions/status/{status}` - List executions by status
|
|
- `GET /executions/enforcement/{enforcement_id}` - List executions by enforcement
|
|
|
|
#### Events (2 endpoints)
|
|
- `GET /events` - List all events (with filters)
|
|
- `GET /events/{id}` - Get event by ID
|
|
|
|
#### Enforcements (2 endpoints)
|
|
- `GET /enforcements` - List all enforcements (with filters)
|
|
- `GET /enforcements/{id}` - Get enforcement by ID
|
|
|
|
#### Inquiries (8 endpoints)
|
|
- `GET /inquiries` - List all inquiries (with filters)
|
|
- `POST /inquiries` - Create new inquiry
|
|
- `GET /inquiries/{id}` - Get inquiry by ID
|
|
- `PUT /inquiries/{id}` - Update inquiry
|
|
- `DELETE /inquiries/{id}` - Delete inquiry
|
|
- `GET /inquiries/status/{status}` - List inquiries by status
|
|
- `GET /executions/{execution_id}/inquiries` - List inquiries for execution
|
|
- `POST /inquiries/{id}/respond` - Respond to inquiry
|
|
|
|
#### Keys/Secrets (5 endpoints)
|
|
- `GET /keys` - List all keys
|
|
- `POST /keys` - Create new key
|
|
- `GET /keys/{ref}` - Get key by reference
|
|
- `PUT /keys/{ref}` - Update key
|
|
- `DELETE /keys/{ref}` - Delete key
|
|
|
|
#### Workflows (7 endpoints)
|
|
- `GET /workflows` - List all workflows (with filtering by tags, enabled status, search)
|
|
- `POST /workflows` - Create new workflow
|
|
- `GET /workflows/{ref}` - Get workflow by reference
|
|
- `PUT /workflows/{ref}` - Update workflow
|
|
- `DELETE /workflows/{ref}` - Delete workflow
|
|
- `GET /workflows/id/{id}` - Get workflow by ID
|
|
- `GET /packs/{pack_ref}/workflows` - List workflows by pack
|
|
|
|
### 3. DTO Schemas
|
|
|
|
All Data Transfer Objects (DTOs) are properly documented with `ToSchema` or `IntoParams` attributes:
|
|
|
|
**Request DTOs:**
|
|
- Authentication: LoginRequest, RegisterRequest, RefreshTokenRequest, ChangePasswordRequest
|
|
- Packs: CreatePackRequest, UpdatePackRequest
|
|
- Actions: CreateActionRequest, UpdateActionRequest
|
|
- Triggers: CreateTriggerRequest, UpdateTriggerRequest
|
|
- Sensors: CreateSensorRequest, UpdateSensorRequest
|
|
- Rules: CreateRuleRequest, UpdateRuleRequest
|
|
- Inquiries: CreateInquiryRequest, UpdateInquiryRequest, RespondToInquiryRequest
|
|
- Keys: CreateKeyRequest, UpdateKeyRequest
|
|
|
|
**Response DTOs:**
|
|
- Full responses: PackResponse, ActionResponse, TriggerResponse, SensorResponse, RuleResponse, ExecutionResponse, EventResponse, EnforcementResponse, InquiryResponse, KeyResponse
|
|
- Summary responses: PackSummary, ActionSummary, TriggerSummary, SensorSummary, RuleSummary, ExecutionSummary, EventSummary, EnforcementSummary, InquirySummary, KeySummary
|
|
- Auth: TokenResponse, CurrentUserResponse
|
|
- Workflow: WorkflowResponse, WorkflowSummary
|
|
- Queue Stats: QueueStatsResponse
|
|
|
|
**Query Parameter DTOs (IntoParams):**
|
|
- PaginationParams
|
|
- EventQueryParams
|
|
- EnforcementQueryParams
|
|
- ExecutionQueryParams
|
|
- InquiryQueryParams
|
|
- KeyQueryParams
|
|
- WorkflowSearchParams
|
|
|
|
**Common DTOs:**
|
|
- ApiResponse<T>
|
|
- PaginatedResponse<T>
|
|
- PaginationMeta
|
|
- SuccessResponse
|
|
|
|
### 4. Security Schemes
|
|
|
|
JWT Bearer authentication is properly configured and referenced in protected endpoints:
|
|
- Security scheme: `bearer_auth`
|
|
- Format: JWT
|
|
- Header: `Authorization: Bearer <token>`
|
|
|
|
Protected endpoints include the `security(("bearer_auth" = []))` attribute.
|
|
|
|
### 5. Tags
|
|
|
|
Endpoints are organized by logical tags:
|
|
- `health` - Health check endpoints
|
|
- `auth` - Authentication and authorization
|
|
- `packs` - Pack management
|
|
- `actions` - Action management
|
|
- `triggers` - Trigger management
|
|
- `sensors` - Sensor management
|
|
- `rules` - Rule management
|
|
- `executions` - Execution queries
|
|
- `events` - Event queries
|
|
- `enforcements` - Enforcement queries
|
|
- `inquiries` - Inquiry (human-in-the-loop) management
|
|
- `secrets` - Secret/key management
|
|
|
|
## Accessing the Documentation
|
|
|
|
Once the API server is running, the interactive Swagger UI documentation is available at:
|
|
|
|
```
|
|
http://localhost:8080/docs
|
|
```
|
|
|
|
The raw OpenAPI JSON specification is available at:
|
|
|
|
```
|
|
http://localhost:8080/api-spec/openapi.json
|
|
```
|
|
|
|
## Testing
|
|
|
|
All OpenAPI annotations have been validated:
|
|
- ✅ Compilation succeeds without errors
|
|
- ✅ OpenAPI spec generation test passes
|
|
- ✅ All DTOs properly implement required traits
|
|
- ✅ Path count test confirms 62 unique paths
|
|
- ✅ Operation count test confirms 86 total operations
|
|
|
|
## Benefits
|
|
|
|
1. **Interactive Documentation**: Developers can explore and test API endpoints directly in the browser
|
|
2. **Auto-Generated Client SDKs**: The OpenAPI spec can be used to generate client libraries in multiple languages
|
|
3. **API Contract**: Serves as the source of truth for API structure and behavior
|
|
4. **Validation**: Request/response schemas are explicitly defined and validated
|
|
5. **Discoverability**: All endpoints, parameters, and response formats are self-documented
|
|
|
|
## Future Enhancements
|
|
|
|
Potential improvements for future iterations:
|
|
- Add more detailed examples for complex request bodies
|
|
- Include error response schemas for specific error cases
|
|
- Add response headers documentation where relevant
|
|
- Document rate limiting headers
|
|
- Add webhook documentation if/when implemented |