re-uploading work
This commit is contained in:
238
docs/api/openapi-spec-completion.md
Normal file
238
docs/api/openapi-spec-completion.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user