task-api-spec.yaml

openapi: 3.0.3
info:
  title: Task Management API
  description: A fully featured API for managing tasks with REST and GraphQL support.
  version: 1.0.0


security:
  - OAuth2: []

servers:
  - url: https://api.example.com
    description: Production Server
  - url: http://localhost:8080
    description: Local Development Server

paths:
  /tasks:
    get:
      summary: Get all tasks
      operationId: findAll
      description: Retrieve a paginated list of all tasks with optional filters.
      parameters:
        - name: taskStatus
          in: query
          schema:
            type: string
            enum: [pending, in_progress, completed]
          description: Filter tasks by taskStatus.
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          description: Pagination - page number.
        - name: size
          in: query
          schema:
            type: integer
            default: 10
          description: Pagination - number of tasks per page.
      responses:
        '200':
          description: List of tasks retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskPage'
    post:
      summary: Create a new task
      operationId: create
      description: Add a new task to the system.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreateRequest'
      responses:
        '201':
          description: Task created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /tasks/{id}:
    get:
      summary: Get a specific task
      operationId: get
      description: Retrieve details of a task by its ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Task details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          description: Task not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      summary: Update a task
      description: Modify an existing task.
      operationId: update
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskUpdateRequest'
      responses:
        '200':
          description: Task updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Task not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Delete a task
      operationId: delete
      description: Permanently remove a task by its ID (hard delete).
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':  # ✅ Change 204 -> 200 with response body
          description: Task deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '404':
          description: Task not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: " http://localhost:8080/api/auth/login"  # Replace with your token endpoint
          scopes: {}
  schemas:
    Task:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
          minLength: 3
          maxLength: 100
        description:
          type: string
        taskStatus:
          type: string
          enum: [pending, in_progress, completed]
        dueDate:
          type: string
          format: date
    TaskCreateRequest:
      type: object
      required: [title, dueDate, taskStatus]
      properties:
        title:
          type: string
          minLength: 3
          maxLength: 100
          description: Title must be between 3 and 100 characters.
        description:
          type: string
        taskStatus:
          type: string
          enum: [pending, in_progress, completed]
        dueDate:
          type: string
          format: date
          description: Due date must be a valid date in the format YYYY-MM-DD.
    TaskUpdateRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 3
          maxLength: 100
          description: Title must be between 3 and 100 characters.
        description:
          type: string
        taskStatus:
          type: string
          enum: [pending, in_progress, completed]
        dueDate:
          type: string
          format: date
          description: Due date must be a valid date in the format YYYY-MM-DD.
    TaskPage:
      type: object
      properties:
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/Task'
        totalPages:
          type: integer
        totalItems:
          type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing the issue.
        details:
          type: array
          items:
            type: string
          description: Detailed validation errors, if applicable.