Add comprehensive OpenAPI specifications to all FastAPI endpoints

[Copilot]

This PR implements comprehensive OpenAPI specifications for all API endpoints in the DECODE OpenCloud Worker-facing API, ensuring proper documentation and validation as required by the issue.

Changes Made

Enhanced all 10 FastAPI endpoints with complete specifications:

• Added response_model parameters with proper Pydantic models
• Added explicit status_code parameters (200, 201, 204)
• Added comprehensive responses documentation including error codes (400, 403, 404, 500)
• Ensured all endpoints have descriptive description parameters
• Added rich examples to Pydantic models for OpenAPI documentation

Updated Pydantic schemas with Field examples:

• FileHTTPRequest - HTTP request examples with realistic URLs and headers
• HardwareSpecs - GPU/CPU specifications with model examples (RTX3080, ampere architecture)
• MetaSpecs - Job metadata with ISO timestamp examples
• AppSpecs - Application command and environment variable examples
• HandlerSpecs - Container image URLs and file path mappings
• PathsUploadSpecs - S3 bucket path examples
• SubmittedJob - Complete job submission examples with priorities and groups

Created new response models:

• WelcomeMessage - For the root endpoint response
• UploadSuccess - For file upload confirmations
• HTTPErrorDetail - For standardized error responses

Example of enhanced endpoint specification:

@router.get(
    "/jobs/{job_id}/status",
    response_model=JobStates,
    status_code=200,
    responses={
        200: {"description": "Job status retrieved successfully"},
        404: {"description": "Job not found"},
    },
    description="Get the status of a job",
)

The OpenAPI specification now includes proper examples for all request/response models:

class HardwareSpecs(BaseModel):
    cpu_cores: int | None = Field(default=None, example=2)
    memory: int | None = Field(default=None, example=4096)
    gpu_model: str | None = Field(default=None, example="RTX3080")

Validation

• All endpoints now generate comprehensive OpenAPI 3.1.0 specifications
• Added static validation tests to ensure decorator parameters are present
• Runtime testing confirms the API serves proper JSON responses with examples
• All code passes linting checks with no regressions

Visual Result

The API now serves structured responses with proper typing:

The OpenAPI documentation (available at /docs) now includes comprehensive endpoint documentation with examples, proper status codes, and detailed response schemas that will help developers understand and integrate with the API effectively.

Fixes #35.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

@nolan1999 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.

[nolan1999]

The github actions are failing because of the wrong poetry version. Please correct this. Ideally, the jobs would read the required version from pyproject.toml directly.

[nolan1999]

The github actions are failing because of the wrong poetry version. Please correct this. Ideally, the jobs would read the required version from pyproject.toml directly.