todo-task-api.yaml

openapi: 3.0.0
info:
    version: 1.0.0
    title: To-Do Task Management API
    description: A simple API for managing to-do tasks. Supports full CRUD operations for tasks in a single-user context.
paths:
    /tasks:
        get:
            summary: List all tasks
            description: Retrieve a list of all tasks, with optional filtering by completion status and due date.
            parameters:
                - in: query
                  name: completed
                  schema:
                    type: boolean
                  description: Filter tasks by completion status (true or false)
                - in: query
                  name: dueDate
                  schema:
                    type: string
                    format: date
                  description: Filter tasks by due date (YYYY-MM-DD)
            responses:
                "200":
                    description: A list of tasks
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: "#/components/schemas/Task"
        post:
            summary: Create a new task
            description: Add a new task to the to-do list.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/TaskInput"
            responses:
                "201":
                    description: Task created successfully
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/Task"
    /tasks/{taskId}:
        parameters:
            - in: path
              name: taskId
              required: true
              schema:
                  type: string
        get:
            summary: Get a task by ID
            description: Retrieve a specific task by its unique ID.
            responses:
                "200":
                    description: Task details
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/Task"
                "404":
                    description: Task not found
        put:
            summary: Update a task
            description: Update an existing task by its ID.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/TaskInput"
            responses:
                "200":
                    description: Task updated successfully
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/Task"
                "404":
                    description: Task not found
        delete:
            summary: Delete a task
            description: Remove a task from the list by its ID.
            responses:
                "204":
                    description: Task deleted successfully
                "404":
                    description: Task not found
components:
    schemas:
        Task:
            type: object
            properties:
                id:
                    type: string
                    example: "1"
                title:
                    type: string
                    example: Buy groceries
                description:
                    type: string
                    example: Milk, bread, eggs
                dueDate:
                    type: string
                    format: date
                    example: 2026-01-01
                completed:
                    type: boolean
                    default: false
                    example: false
            required: 
                - id
                - title
                - completed
        TaskInput:
            type: object
            properties:
                title:
                    type: string
                    example: Buy groceries
                description:
                    type: string
                    example: Milk, bread, eggs
                dueDate:
                    type: string
                    format: date
                    example: 2026-01-01
                completed:
                    type: boolean
                    default: false
                    example: false
            required:
                - title
                - completed