todos.openapi.yml

openapi: 3.0.2
info:
  title: ToDos API
  description: A simple CRUD API
  version: 0.0.1

tags:
  - name: ToDos
    description: the ToDo resource

paths:
  /todos:
    get:
      tags: [ ToDos ]
      summary: List all ToDos
      operationId: listToDos
      parameters:
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
      responses:
        '200':
          $ref: '#/components/responses/ToDoList'
    post:
      tags: [ ToDos ]
      summary: Add a new ToDo
      operationId: createToDo
      requestBody:
        $ref: '#/components/requestBodies/ToDo'
      responses:
        '201':
          $ref: '#/components/responses/ToDo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []
  /todos/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags: [ ToDos ]
      summary: Get a ToDo
      operationId: getToDo
      responses:
        '200':
          $ref: '#/components/responses/ToDo'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags: [ ToDos ]
      summary: Update a ToDo
      operationId: patchToDo
      requestBody:
        $ref: '#/components/requestBodies/ToDo'
      responses:
        '200':
          $ref: '#/components/responses/ToDo'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []
    delete:
      tags: [ ToDos ]
      summary: Delete a ToDo
      operationId: deleteToDo
      responses:
        '204':
          description: Empty response
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - basicAuth: []

components:
  schemas:
    ToDo:
      properties:
        id:
          type: string
          readOnly: true
          example: "fd1a8610-8aa2-485c-880a-90e43ec189c3"
        createdAt:
          type: string
          readOnly: true
          example: "4020-04-20T16:20:00.000000+0000"
          format: date-time
        name:
          type: string
          example: "Pay the bills"
        dueFor:
          type: string
          example: "4020-04-20T16:20:00.000000+0000"
          format: date-time
        doneAt:
          type: string
          example: "4020-04-20T16:20:00.000000+0000"
          format: date-time
        isDone:
          type: bool
          readOnly: true
      required:
        - id
        - name
    GenericError:
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: integer
          required:
            - message
            - code
    InvalidDataError:
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: integer
            details:
              type: object
              example:
                messageIdentifier: detailed message
          required:
            - message
            - code

  requestBodies:
    ToDo:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ToDo'
    ToDoRating:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ToDoRating'

  responses:
    ToDo:
      description: A single ToDo
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ToDo'
    ToDoList:
      description: A list of ToDos
      content:
        application/json:
          schema:
            properties:
              items:
                type: array
                items:
                  $ref: '#/components/schemas/ToDo'
              nextPage:
                type: integer
                example: 2
              prevPage:
                type: integer
                example: null
              totalPages:
                type: integer
                example: 2
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericError'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InvalidDataError'
    Unauthorized:
      description: Authentication failed
      content: {}
      headers:
        WWW-Authenticate:
          schema:
            type: string
          description: Supported authentication schema

  parameters:
    id:
      in: path
      name: id
      description: A string representation of a UUID
      required: true
      schema:
        type: string
        format: uuid
        example: 'fd1a8610-8aa2-485c-880a-90e43ec189c3'
    search:
      name: search
      in: query
      schema:
        type: string
        example: 'pay'
      description: Full text search phrase
    page:
      name: page
      in: query
      schema:
        type: integer
        default: 1
        example: 1
      description: The page number
    pageSize:
      name: pageSize
      in: query
      schema:
        type: integer
        default: 20
        example: 20
      description: The maximum page size
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic

security:
  - basicAuth: []