api.yaml

openapi: "3.0.3"
info:
  title: Controle de Ponto API
  version: "1.0"
components:
  schemas:
    Erro:
      type: object
      properties:
        mensagem:
          type: string
    Batida:
      type: object
      description: Batida de ponto
      properties:
        momento:
          description: Momento da batida
          type: string
          example: "2018-08-22T08:00:00"
    Expediente:
      type: object
      description: Jornada diária de trabalho
      properties:
        dia:
          type: string
          format: date
        pontos:
          type: array
          example: ["08:00:00", "12:00:00", "13:00:00", "18:00:00"]
          items:
            type: string
    Relatorio:
      type: object
      description: Relatório mensal
      properties:
        anoMes:
          format: ISO 8601.Duration
          type: string
          example: 2018-08
        horasTrabalhadas:
          format: ISO 8601.Duration
          type: string
          example: PT69H35M5S
        horasExcedentes:
          type: string
          example: PT25M5S
        horasDevidas:
          format: ISO 8601.Duration
          type: string
          example: PT0S
        expedientes:
          type: array
          items:
            $ref: '#/components/schemas/Expediente'
paths:
  /v1/batidas:
    post:
      tags: 
        - "Batidas"
      summary: "Bater ponto"
      description: "Registrar um horário da jornada diária de trabalho"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Batida"
      responses:
        "201":
          description: |
            Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Expediente"
        "400":
          description: |
            Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Erro"
              examples:
                Almoço:
                  value:
                    mensagem: Deve haver no mínimo 1 hora de almoço
                Campo Obrigatório:
                  value:
                    mensagem: Campo obrigatório não informado
                Formato Inválido:
                  value:
                    mensagem: Data e hora em formato inválido
                4 Horários:
                  value:
                    mensagem: Apenas 4 horários podem ser registrados por dia
                Sábado/Domingo:
                  value:
                    mensagem: Sábado e domingo não são permitidos como dia de trabalho
        "409":
          description: |
            Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Erro"
              examples:
                Horário já registrado:
                  value:
                    mensagem: Horário já registrado
  /v1/folhas-de-ponto/{anoMes}:
    get:
      tags:
        - Folhas de Ponto
      summary: "Relatório mensal"
      description: "Geração de relatório mensal de usuário."
      parameters:
        - name: anoMes
          in: path
          required: true
          schema:
            type: string
            example: "2018-08"
      responses:
        "200":
          description: Relatório mensal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Relatorio"
        "404":
          description: Relatório não encontrado