attune/docs/api/openapi-spec-completion.md

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
• PaginatedResponse
• 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