Rapidamente
OpenAPI é uma especificação criada pela iniciativa Open API para descrever, produzir, consumir e visualizar serviços no protocolo REST de forma que máquinas consigam ler (sim, isso está no Google). OpenAPI specification também é conhecida como Swagger specification para quem estava acostumado já com essa nomenclatura.
O objetivo desse texto é te mostrar como trazer essa especificação a favor de sua esteira de desenvolvimento e se antecipar a erros que só viriam aparecer durante ou após a conclusão de endpoints.

Devo documentar minha API?
Sim, você deve documentar sua API principalmente quando outros desenvolvedores de outras tecnologias vão consumi-la. A grande razão para documentar uma API é que o formato utilizado para descreve-las deve ser mais detalhado em relação aos padrões REST. Um doc word contendo uma tabela com o caminho requisição, corpo e possíveis retornos torna-se pouco útil quando sua API REST sofrerá manutenções — o que quase não acontece certo? — já que a pessoa responsável por documentar terá que esperar a API ficar pronta e testada para assim atualizar o tal documento e disponibiliza-lo, além de ter um padrão próprio de formatação.

Como é
A notação necessária para especificar é toda baseada no formato YAML estruturado com tabulações, ou seja, se você já precisou interagir com JSON vai ver mais facilidade ainda em escrever nesse formato. O arquivo pode acessar outros arquivos externos e é interpretado por várias ferramentas e plugins.

A esquerda a espeficiação OpenAPI e a direita a preview testável provida pelo site https://editor.swagger.io

Ficou curioso? Você pode encontrar mais informações na própria página da especificação (https://swagger.io/docs/specification/about/) e brincar com o modelo de “petstore” já criado pelo https://editor.swagger.io. Como já dito, o objetivo aqui não é te mostrar como fazer sua especificação de API REST e sim trazer um cenário que vai favorecer o levantamento de dados e comunicação entre os times para uma implementação mais rápida e assertiva usando essa especificação.

É agora: desenvolvimento guiado por dados
Vamos imaginar o seguinte cenário: Você faz parte do time de back-end e precisa desenvolver uma API REST. Na mesma sala se encontram os times de front-end web, mobile (este que será uma empresa terceira) e qualidade.

Pensando de maneira segmentada, o pessoal do front e mobile vão começar a montar o setup do projeto, protótipos ou esperar o back-end liberar a primeira API para começar a consumir. O time de qualidade pode buscar informações para criar casos de testes e só depois da API desenvolvida vai ter uma idéia de como serão os dados.

Ficou bem claro aqui que há uma suave, sucinta e humilde pressão para que o time de back-end conclua o quanto antes o primeiro endpoint para todos “começarem a trabalhar oficialmente no projeto”.

Modelo onde o back-end deve desenvolver primeiro para os clients consumirem a API.

OK, Você pode até argumentar que o back-end sempre anda uma, duas sprints à frente para garantir que tudo estará disponível aos demais times. Pois bem, e se pudéssemos todos iniciar na mesma sprint? Isso pode acontecer definindo os dados das APIs a serem implementadas. Esse conceito é chamado de API-First Design. Ainda podemos usar ferramentas de OpenAPI (https://openapi.tools/) que partem desde plugins para até geradores de código e mocks.

Modelo API First

No modelo API First, os dados e suas definições começam pelo consumidor, no nosso caso os times de front-end e mobile. Com este contrato definido, o implementador da API (back-end) deve atender aquele destino de requests e reponses com sua linguagem e framework REST ideal enquanto os demais times já podem desenvolver o consumo dos endpoints.

E o time de qualidade? — Você deve estar se perguntando — Espero que suas APIs REST estejam sendo testadas de forma automatizada, caso não, procure ferramentas como Postman e Insomnia. Falando nestas ferramentas, ambas importam o formato OpenAPI 3.0 e já criam os testes sendo um ganho de tempo muito expressivo para quem precisa montar as automações e validações.

Prós e contras
É, como toda proposta ela vai te levar a uma escolha e uma renúncia. Observei e vivenciei alguns pontos positivos e negativos no uso de uma documentação de API.
Prós:

  • Uma única fonte de verdade para os times
  • Clareza por estar 100% adequado com o modelo REST
  • Ganho de tempo em features
  • Resposta rápida a mudanças do negócio
  • Muitas ferramentas compatíveis para gerar código e mocks

Contras:

  • Comunicação entre os times deve ser mais frequente (avisos sobre atualizar a doc)
  • Versionamento da API deve ser frequente (sim, jogue no repositório git)
  • Necessário sólido conhecimento no modelo RESTful por parte dos clients
  • Aumento de erros simultâneos entre os times caso a documentação tenha sido falha.

Plugins para documentação de API no código-fonte
Em alguns frameworks de backend como .NET, Spring, Ruby on Rails temos plugins do Swagger para implementar a documentação da API desenvolvida. A questão é: Devemos continuar documentando em nosso código já que o projeto de OpenAPI existirá também? Minha resposta para essa questão é que se você irá divulgar essa API para terceiros, o ideal é documentar usando plugins sim, pois não é prudente exigir que todos saibam visualizar arquivos OpenAPI (apesar do VSCode ter um plugin muito bom para isso). Caso for usar para sua empresa somente, um projeto OpenAPI substitui este trabalho.

Últimas recomendações
O uso do OpenAPI deve respeitar a regra de que o que está descrito no arquivo é a fonte de verdade entre a comunicação dos times. Criar um repositório e atualizar sempre as estruturas de arquivos é mais do que obrigatório para que todos os envolvidos tenham o acesso da “verdade mais recente”.
Por fim, todos terão uma visibilidade mais rápida de como os dados vão transitar e a curva de aprendizado para práticas no modelo RESTful vai diminuir pois a prática exigirá dos profissionais uma visão mais homogênea do formato de seus endpoints.

Espero ter contribuído para seu aprendizado de hoje e comente aqui se já usa ou pretende implementar API First no seu próximo projeto.
Obrigado por ler até aqui, deixe um aplauso e conheça a agileeze!