Frameworksp

Atalhos

Páginas filhas
  • DEAITOOLS-184 - Definir bases iniciais para o desenvolvimento da ferramenta de edição de APIs e Schemas
  • Criado por Usuário desconhecido (francisco.cardoso), última alteração em 26 abr, 2019

Propósito

O objetivo desse Spike foi o de realizar um levantamento a respeito do desenvolvimento de uma ferramenta que facilitasse, graficamente, a edição da documentação X-TOTVS.

Foi sugerido um estudo de ferramentas Open Source antes de considerarmos o desenvolvimento de uma ferramenta própria.

Iniciamos esse documento explicando sobre o levantamento de problemas realizado com usuários chave, em seguida, sobre a pesquisa comparativa de ferramentas.
Todos os outros tópicos que se seguem, são à respeito do projeto apicurio, que foi a ferramenta selecionada para aprofundamento.

Levantamento de Problemas

Inicialmente, foi verificada uma falta de iniciativas de alteração das documentações X-TOTVS, a fim de mantê-las atualizadas.
Provável causa é a dificuldade de fazê-la na estrutura do documento, e ter que passar por todo o processo de pull request e aprovação.

Além disso, foi realizado um levantamento através de tópico no Ryver:
https://totvs.ryver.com/index.html#posts/2072879

Os problemas identificados nesse tópico foram:

  • Entendimento nos erros apresentados pelo validador
  • Dificuldade ao utilizar Git / GitHub
  • Dificuldade ao realizar o design de APIs mais complexas (de process;, com entidade filhas/ligadas...)
  • Falta de exemplos/templates de documentações de APIs (Antes)
  • Falta de exemplos/templates de códigos fonte para APIs (Ainda acontece)

Pesquisa de Ferramentas

Foram verificadas as seguintes ferramentas Open Source:


O primeiro foi selecionado (Apicurio), devido aos seguintes motivos:

  • Melhor UX 
  • Maturidade do projeto
  • Atividade recente no projeto
  • Mantido pela RedHat
  • Tecnologias utilizadas (Angular e Java)
  • Suporte à versão 3.x
  • Integrações diversas (Repositórios e outras aplicações)

Licenciamento

A licença do projeto é a Apache License 2.0, que é bastante permitiva. Permite uso comercial, modificação e distribuição.

Arquitetura

O apicurio é divido nos seguintes componentes:

  • UI
  • API
  • Websockets (real-time collaboration with other users)
  • Keycloak (Authentication)
  • Microcks (Fake APIs implementations)

Possíveis Ganhos 

  • Facilitar a edição dos "x-totvs" 
    • Integração diretamente com a master (Diminuir burocracia e tempo de publicação)
  • Colaboração, divulgação e avaliação do comitê
  • Democratização do Design de APIs 
    • O cliente ainda precisa conhecer apenas boas práticas REST
    • O cliente não precisa conhecer JSON / JsonSchema / OpenAPI
    • O cliente não precisa conhecer GIT, PullRequests...
  • Experiência de UX indolor, refinada e agradável. (Não foi um problema apontado no levantamento)

Vantagens Técnicas

  • Arquitetura bem organizada em camadas (FrontEnd/BackEnd/APIs/Injeção de dependências)
  • Tecnologias conhecidas pela equipe (Angular e Java)
  • Código bem escrito, organizado e comentado
  • Open Source. Projeto em constante evolução, facilidade em trazer atualizações feitas pela comunidade, abertura de issues e pullrequests.

Riscos de Projeto

  • Projeto extremamente grande, o que o torna complexo
  • Dificuldades na manipulação da estrutura do OpenAPI.
    • O frontend utiliza bibliotecas externas para manipulação dos objetos OpenAPI. Nós teremos que incluir a base de código dessa biblioteca no nosso projeto para inclusão dos campos personalizados, e seus tratamentos.
  • Problemas ao derreferenciar
    • O projeto atualmente precisa que exista uma quebra entre o OpenAPI e schema dentro do próprio arquivo, para ele identificar os datatypes. 
    • Não funciona com links para arquivos externos
    • Não funciona com a propriedade "components/schemas" vazia
  • Complexidade ao fazer a quebra dos arquivos (OpenAPI / JSONSchema)
    • No momento de salvar, vamos ter que "na mão" realizar a quebra da maneira que definimos (Dois arquivos).
      • As bibliotecas padrão não fazem isso.
  • Integrações com ferramentas das quais não temos conhecimento, como Keycloak e Microcks
  • Preocupação com suporte
    • Falta de controle no tempo de resposta de issues abertas no GitHub
    • Possibilidade de assinatura de um suporte oficial / cobrança?

Entrega

Como resultado desse Spike, foram gerados os seguintes artefatos:

Futuro

Após discussão, esse foi o futuro definido para esse projeto:

  • Mapearemos o que é imprescindível e o que é desejável (must-have e nice-to-have) do projeto. Priorizar. 
  • Será criado um épico em relação a isso, e criaremos as issues de acordo com as prioridades.

Outras possibilidades discutidas ao longo da reunião:

  • Fazer uma versão enxuta, "enxugando" algumas funcionalidades existentes, fazendo apenas o que considerarmos como ponto focal
  • Continuar estudo
    • Buscar resolver os problemas no processo
    • Se aprofundar em outras ferramentas
    • Desenvolvimento de ferramenta própria 
  • Desistir desse projeto

RoadMap

Must Have

  1. Integrações para ações no repositórios
    1. Integração do backend com nosso repositório do GitHub
      1. Abrir pull requests em nome do usuário
    2. Integração do backend com o comparador de OpenAPIs
      1. Identificar cenários em que apenas o XTOTVS foi alterado.
      2. Permitir que, quando o cenário acima for verdadeiro, o commit do documento seja realizado diretamente na master
  2. Manipulação das customizações TOTVS no OAS 3.X
    1. Incluir os fontes de manipulação do OpenAPI no nosso projeto. 
      1. Adaptar os mesmos para estrutura X-TOTVS (Modelos e lógica de parseamento)
    2. Trabalhar nos componentes para exibir/atualizar os elementos do X-TOTVS
    3. Trabalhar a lógica de derreferenciar as arquivos externos
    4. Trabalhar a lógica de separar o artefato gerado em dois documentos

Nice To Have

  1. Pipeline CI/CD 
    1. Quanto antes isso for realizado, maior o ganho de produtividade da equipe (Tempo gasto com outras maneiras de deploy durante evolução do projeto)
    2. Entender se precisamos fazer alguma alteração no dockerfile existente
    3. Solicitar apoios necessários: Repositório do docker.totvs,  namespace Kubernets, DNS...
    4. Configurar pipeline de build da imagem e deploy através do github 
  2. Validações
    1. Externalizar serviço para as mesmas validações existentes no CI do Github.
    2. Consumir o serviço descrito acima na interface de usuário, para preencher a lista de validações na coluna da direita, conforme o usuário for preenchendo os campos
  3. Colaboração
    1. Estudar como funciona a edição real time de uma mesma API por mais de um usuário, convites de colaboração...
    2. Ativar colaboração
  4. Integração com provider de autenticação
    1. Estudar utilizar o nosso Identity Manager
    2. Implementar integração
  5. Integração com Microcks
    1. Estudar como utilizar essa integração, e se existe alguma mudança necessária em relação à implementação padrão
    2. Ativar integração
  6. Gerador de projetos através de Wizard
    1. Customizar gerador para fornecer Templates de código em TL++, Java... 

Reflexão

Are you a problem solver... or a solution creator?


  • Sem rótulos