Interface de integração OpenAPI

Para realizar os propósitos funcionais desta aplicação, as seguintes operações devem ser realizadas:

• Inicialização de uma nova lista de checagem padronizada compatível com um dos quatro tipos: IGF - C (Custos), IGF - F (Faturamento), IGF - L (Lançamentos), IGF - R (Resultados).
• Gravação de score para cada item respondido pelo usuário.
• Recálculo do score da lista a partir de cada item respondido pelo usuário.
• Gravação de justificativas e encerramento.

Para satisfazer essas operações, o seguinte pseudo-contrato foi desenhado:

• indices: Operação do tipo GET para listagem dos tipos disponíveis.
• questionario: Operação do tipo POST para inicialização de uma nova lista de itens a partir de um tipo especificado.
• questionario/calculoIGF: Operação do tipo PATCH para atualização de um ou mais itens modificados pelo usuário.
• questionario/finalizado: Operação do tipo PUT para atualização da lista e dos itens da lista, inclusão de justificativas e encerramento do preenchimento.
• questionarios: Operação do tipo GET para listagem das listas preenchidas.

Em linha com as práticas de trabalho definidas, foi estabelecido um "contrato" de interface do tipo OpenAPI, versão 3.0.1.

Para refinamento do contrato, foi utilizada o editor de contratos swagger editor ⧉.

A versão básica do contrato OpenAPI está apresentado abaixo.

Contrato Integração

openapi: 3.0.1
info:
  title: MITH - POC-API de Indices
  description: Poc demonstrativa cálculo índices de projeto.
  contact:
    name: Greydmar Cunha
    url: >-
      https://git.magnasistemas.com.br/mith/labs/poc_indices-de-gest-o-magna/java/backend
    email: gcunha@magnasistemas.com.br
  version: 0.1.2
servers:
  - url: https://localhost:50432
    description: Server URL in Development environment
  - url: https://localhost:50015
    description: Server URL in Production environment
tags:
  - name: questionario
    description: Gestão de preenchimento do questionário
  - name: questionarios
    description: Consulta simples de questionários
  - name: indices
    description: the indices API
paths:
  /api/v2/questionario/finalizado:
    put:
      tags:
        - questionario
      operationId: apiV2QuestionarioFinalizadoPut
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReqRespostaQuestionario'
          text/json:
            schema:
              $ref: '#/components/schemas/ReqRespostaQuestionario'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ReqRespostaQuestionario'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Questionario'
  /api/v2/questionario/novo:
    post:
      tags:
        - questionario
      operationId: apiV2QuestionarioPost
      requestBody:
        content:
          application/json:
            schema:
              type: string
          text/json:
            schema:
              type: string
          application/*+json:
            schema:
              type: string
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Questionario'
  /api/v2/questionario/calculoIGF:
    patch:
      tags:
        - questionario
      operationId: apiV2QuestionarioCalculoIGFPatch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReqRespostaQuestionario'
          text/json:
            schema:
              $ref: '#/components/schemas/ReqRespostaQuestionario'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ReqRespostaQuestionario'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Questionario'
  /api/v2/questionarios:
    get:
      tags:
        - questionarios
      operationId: apiV2QuestionariosGet
      parameters:
        - name: codigoIndice
          in: query
          description: Código do Índice
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Questionario'
  /api/v2/indices:
    get:
      tags:
        - indices
      operationId: apiV2IndicesGet
      parameters:
        - name: sortBy
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Indice'
components:
  schemas:
    Questao:
      required:
        - id
        - versao
      type: object
      properties:
        id:
          maxLength: 10
          type: string
        idQuestionario:
          type: string
        versao:
          type: integer
          format: int32
        textoApresentado:
          type: string
        textoJustificativa:
          maxLength: 500
          type: string
        pesoAtribuido:
          maximum: 5
          type: integer
          format: int32
    Questionario:
      required:
        - codigoIndice
        - id
      type: object
      properties:
        id:
          maxLength: 48
          type: string
        codigoIndice:
          maxLength: 20
          type: string
        valorIGF:
          type: number
        versao:
          type: integer
          format: int32
        situacao:
          type: string
          enum:
            - Disponivel
            - EmPreenchimento
            - Finalizado
        items:
          type: array
          items:
            $ref: '#/components/schemas/Questao'
    ReqRespostaQuestao:
      required:
        - id
      type: object
      properties:
        id:
          maxLength: 10
          type: string
        idQuestionario:
          maxLength: 48
          type: string
        textoJustificativa:
          maxLength: 500
          type: string
        pesoAtribuido:
          maximum: 5
          type: integer
          format: int32
    ReqRespostaQuestionario:
      required:
        - id
      type: object
      properties:
        id:
          maxLength: 48
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/ReqRespostaQuestao'
    Indice:
      required:
        - nomeIndice
      type: object
      properties:
        id:
          type: string
        nomeIndice:
          maxLength: 20
          type: string
        descricao:
          type: string