todos.yaml

swagger: '2.0'
info:
  title: TODO List
  description: API de gerenciamento de tarefas.
  version: '1.0.0'
schemes:
  - https
basePath: /v1
produces:
  - application/json
paths:
  /todos:
    get:
      summary: "Pesquisa tarefas por diferentes filtros"
      description: "Os filtros são informados como query params: /todos?name=tarefa&user=1&completed=false&date=01012022&position=1"
      operationId: "listTodos"
      parameters:
      - name: "name"
        in: "query"
        description: "Nome aproximado da tarefa"
        type: "array"
        items:
          type: "string"
      - name: "user"
        in: "query"
        description: "Usuário dono da tarefa"
        type: "array"
        items:
          type: "integer"
      - name: "completed"
        in: "query"
        description: "Indica se a tarefa foi realizada"
        type: "array"
        items:
          type: "boolean"
      - name: "date"
        in: "query"
        description: "Data de criação / modificação da tarefa"
        type: "array"
        items:
          type: "string"
      - name: "position"
        in: "query"
        description: "Posição da tarefa na lista"
        type: "array"
        items:
          type: "integer"
      - name: "projection"
        in: "query"
        description: "Atributos da tarefa que devem ser retornados"
        type: "array"
        items:
          type: "string"
      - name: "page"
        in: "query"
        description: "Página atual da pesquisa"
        type: integer
      - name: "size"
        in: "query"
        description: "Tamanho da página de pesquisa"
        type: integer
      responses:
        "200":
          description: "Lista de tarefas encontradas"
          schema:
            type: array
            items:
              $ref: "#/definitions/TarefaResponse"
    post:
      summary: "Adiciona uma nova tarefa à lista"
      description: ""
      operationId: "addTodo"
      parameters:
      - in: "body"
        name: "body"
        description: "Tarefa que será adicionada à lista"
        required: true
        schema:
          type: "object"
          properties:
            name:
              type: "string"
            user:
             type: "integer"
      responses:
        "201":
          description: "Tarefa criada com sucesso"
          schema:
            properties:
              id:
                type: integer
        "422":
          description: "Tarefa inválida ou não informada"
          schema:
            $ref: "#/definitions/ErrorResponse"
  /todos/{id}:
    get:
      summary: "Encontra uma tarefa pelo seu id"
      description: "Retorna uma única tarefa"
      operationId: "getTodo"
      parameters:
      - name: "id"
        in: "path"
        description: "ID da tarefa"
        required: true
        type: "integer"
      responses:
        "200":
          description: "Tarefa encontrada retornada"
          schema:
            $ref: "#/definitions/TarefaResponse"
        "404":
          description: "Tarefa não encontrada"
    put:
      summary: "Atualiza uma tarefa"
      description: ""
      operationId: "updateTodo"
      parameters:
      - name: "id"
        in: "path"
        description: "ID da tarefa"
        required: true
        type: "integer"
      - name: "body"
        in: "body"
        description: "Tarefa que será atualizada"
        required: true
        schema:
          type: "object"
          properties:
            name:
              type: string
            completed:
              type: boolean
            position:
              type: integer
      responses:
        "200":
          description: "Tarefa atualizada"
        "404":
          description: "Tarefa não encontrada"
        "422":
          description: "Tarefa com dados inválidos"
          schema:
            $ref: "#/definitions/ErrorResponse"
    delete:
      summary: "Remove uma tarefa da lista"
      description: ""
      operationId: "deleteTodo"
      parameters:
      - name: "id"
        in: "path"
        description: "ID da tarefa"
        required: true
        type: "integer"
      responses:
        "200":
          description: "Tarefa removida"
        "404":
          description: "Tarefa não encontrada"
definitions:
  TarefaResponse:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      user:
        type: integer
      completed:
        type: boolean
      date:
        type: string
      position:
        type: integer
  ErrorResponse:
    type: object
    properties:
      message:
        type: string
      details:
        type: array
        items: 
          type: string