openapi: "3.1.0"
info:
  version: "1.0.0"
  title: A simple Todo app API
paths:
  /todos:
    get:
      summary: List of my TODO items
      operationId: todo.list
      parameters:
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: A list of my TODO items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Item"
        "400":
          $ref: "#/components/responses/ValidationError"
    post:
      summary: Create a TODO item
      operationId: todo.create
      requestBody:
        $ref: "#/components/requestBodies/ItemBody"
      responses:
        "200":
          description: Success message.
          content:
            application/json:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/ValidationError"
  /todos/{todo_id}:
    delete:
      summary: Delete a TODO item
      operationId: todo.delete
      parameters:
        - $ref: "#/components/parameters/todo_id"
      responses:
        "200":
          description: Success message.
          content:
            application/json:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/ValidationError"
    put:
      summary: Update a TODO item
      operationId: todo.update
      parameters:
        - $ref: "#/components/parameters/todo_id"
      requestBody:
        $ref: "#/components/requestBodies/ItemBody"
      responses:
        "200":
          description: Success message.
          content:
            application/json:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/ValidationError"
components:
  parameters:
    limit:
      name: limit
      in: query
      description: The maximum number of TODO items to return
      schema:
        type: integer
        minimum: 1
      required: false
    todo_id:
      name: todo_id
      in: path
      description: The index of the TODO item to edit
      schema:
        type: integer
        minimum: 0
      required: true
  requestBodies:
    ItemBody:
      required: true
      description: Data for creating a new TODO item
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Item"
  schemas:
    Item:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          maxLength: 40
    Error:
      type: object
      required:
        - message
      properties:
        field:
          type: string
        message:
          type: string
        exception:
          type: string
  responses:
    ValidationError:
      description: OpenAPI request/response validation failed
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/Error"