Add Comprehensive API Documentation (OpenAPI/Swagger)

[famvilianity-eng]

Title: Create OpenAPI/Swagger Documentation for All Public APIs

Description: The contract APIs are documented in README but lack formal OpenAPI specification. Create comprehensive OpenAPI docs for smart contract functions, oracle endpoints, and any REST APIs.

Requirements and Context:

• Document all public contract functions (parameters, returns, errors)
• Include oracle integration endpoints
• Add example requests and responses
• Generate interactive Swagger UI
• Security: Document authorization requirements for each endpoint

Suggested Execution: docs/openapi-specification

Implement Changes:

• Create /docs/openapi.yaml with complete API specification
• Generate Swagger UI and host on GitHub Pages
• Add code examples in multiple languages (JS, Rust, Python)
• Link from README to interactive docs

Test and Commit:

• Validate OpenAPI YAML schema
• Generate Swagger UI and test interactivity
• Verify examples execute correctly
• Link documentation from main README

Example Commit Message:

docs: add OpenAPI/Swagger documentation for all APIs

- Create comprehensive OpenAPI specification
- Include contract functions, oracle endpoints, and examples
- Generate interactive Swagger UI
- Add multi-language code examples (JS, Rust, Python)

Guidelines:

• Keep OpenAPI docs in sync with contract changes
• Include curl examples for all endpoints
• Document rate limiting and authorization

---