feat(api): update OpenAPI specification

[alvarobernal2412]

This PR introduces a complete OpenAPI 3.0 specification for the scheduled task management API of the Governify Director project. The documentation defines all endpoints, data schemas, and workflows required for comprehensive task management using JavaScript scripts.

Changes Made

📋 API Specification (api/oas-file.yaml)

• New OpenAPI 3.0 specification for the Task Management API

• 8 main endpoints, organized into 3 categories:

  • Tasks: CRUD operations (GET, POST, PUT, DELETE)
  • Task Status: Status control and monitoring
  • Task Execution: Manual execution and testing

🔧 Core Features Documented

Task Management

• GET /api/v1/tasks – List tasks with filtering via query parameters
• POST /api/v1/tasks – Create a new task with auto-generated UUID
• GET /api/v1/tasks/{id} – Retrieve a specific task by ID
• PUT /api/v1/tasks/{id} – Fully update a task
• DELETE /api/v1/tasks/{id} – Permanently delete a task

Task Status & Monitoring

• GET /api/v1/tasks/{id}/status – Execution status and next run time
• GET /api/v1/tasks/{id}/badge – Visual SVG badge of the current status
• POST /api/v1/tasks/{id}/status/{action} – Control task state (start/stop/switch)

Script Execution

• POST /api/v1/tasks/{id}/run – Manually trigger immediate execution
• POST /api/v1/tasks/test – Test scripts before creating tasks

📊 Data Schemas

• Task: Full representation of a scheduled task
• TaskInput: Required data to create a new task
• TaskStatus: Current execution status
• ExecutionResult: Script execution result
• TestRequest: Data for script testing
• ErrorModel: Standardized error model

🔒 Security

• ApiKeyAuth: API Key authentication via header
• BearerAuth: JWT Bearer token authentication

📖 Documentation Features

• Detailed descriptions for each endpoint and operation
• Complete examples of requests and responses
• Validations and constraints defined in schemas
• Error cases documented with appropriate HTTP codes
• Workflows explained for integration purposes

Benefits

1. Complete documentation of the existing API
2. OpenAPI 3.0 standards for integration with tools
3. Practical examples for developers
4. Clearly defined data validation
5. Foundation for automated testing and SDK generation