Documentação de API de alta qualidade aumenta a satisfação do cliente. No meu post anterior, apresentei meios para gerar documentação OpenAPI para APIs serverless com Powertools para AWS. Com base nessa fundação, este artigo se aprofunda na automação e integração perfeita desse processo em nosso fluxo de trabalho de CI/CD.
Nesta postagem, você aprenderá como gerar documentação OpenAPI para suas APIs sem servidor automaticamente, mantê-la sincronizada com seu código e se proteger contra alterações que podem quebrar a API.
Índice
Recapitulação da documentação do OpenAPI sem servidor
No post anterior , apresentei um método para gerar documentação OpenAPI para APIs baseadas em funções Python Lambda, utilizando Powertools para AWS Lambda e Pydantic.
Gerei uma documentação OpenAPI para uma API serverless que consiste em um API Gateway e uma função Lambda. Defini o esquema de payload de entrada HTTP e TODAS as respostas HTTP possíveis: seus códigos e payload JSON completo com Pydantic. O utilitário manipulador de eventos do Powertool lidou com a geração da documentação.
Ele serviu a documentação sob um novo ponto de extremidade da API: '/swagger'.
Usei meu projeto de modelo de livro de receitas do AWS Lambda e adicionei suporte para documentação OpenAPI. Automatizaremos esse processo e adicionaremos automações de CI/CD adicionais ao pipeline baseado em ação do GitHub de CI/CD do projeto.
O acionamento do endpoint '/swagger' resultou na seguinte documentação:
Caso você não saiba, o Cookbook é um projeto modelo que permite que você comece a usar o serverless com três cliques e tem todas as melhores práticas e utilitários que um serviço serverless de nível de produção exige.
Geração de documentação OpenAPI
Vamos supor que enviamos nossa documentação OpenAPI para os clientes ou a publicamos no site da nossa empresa. A solução apresentada na seção de recapitulação, onde os clientes acessam o endpoint '/swagger' da API, não atende a esses requisitos. Vamos encontrar uma alternativa.
Uma solução possível é adicionar uma automação que extraia a documentação OpenAPI do endpoint '/swagger' e a armazene no repositório GitHub do serviço. Uma vez comprometido com o repositório, podemos enviá-lo para nossos clientes ou publicá-lo no site da nossa empresa.
Um mundo inteiro de automação também se abre.
Apresentarei o método automatizado de geração de documentação OpenAPI e dois guardrails automatizados que você deve adicionar aos seus pipelines de CI/CD. Eles incluem:
Manter o arquivo de documentação local sincronizado com o código o tempo todo.
Falha em uma solicitação de pull no pipeline de CI/CD se ela incluir alterações que quebrem a API.
É importante observar que esses conceitos e automações podem ser reproduzidos em qualquer estrutura de CI/CD, não apenas no GitHub Actions, como apresentado aqui.
Vamos começar extraindo a documentação do OpenAPI e armazenando-a no repositório de serviço de maneira automatizada e repetível.
Automatize a documentação OpenAPI
Quando um desenvolvedor atualiza o código da API, a documentação do OpenAPI também precisa ser atualizada, então os desenvolvedores devem executar a geração da documentação do OpenAPI como parte de seu PR. Vamos automatizar esse processo.
Usaremos o recurso de endpoint swagger do Powertools para gerar uma documentação OpenAPI no formato JSON. Ele já é suportado; precisamos apenas implantar nosso serviço e acessar o endpoint.
Escreveremos um script Python para gerar o arquivo JSON de documentação do OpenApi.
Se você se lembra, o manipulador de eventos do Powertool expõe um endpoint '/swagger' em nosso gateway de API que carrega uma interface de usuário swagger bacana. No entanto, se enviarmos uma solicitação HTTP GET para '/swagger?format=json', obteremos nossa documentação no formato JSON!
Tudo o que precisamos fazer é que o script baixe o arquivo JSON chamando esse endpoint com o parâmetro de consulta e salve-o em uma pasta de saída.
Vamos rever o fluxo geral do script:
Encontre a URL do gateway da API. Usei uma técnica em que armazenei a URL nas saídas da pilha sob a chave 'SwaggerURL'. Gerei o nome da pilha usando uma convenção predefinida e busquei sua saída. O nome da chave de saída da pilha é um argumento de script, e você pode usar qualquer chave que desejar. Mostrei a criação da saída da pilha em meu post anterior. Outra opção é passar a URL como um argumento para o script.
Baixe o arquivo JSON. Envie uma solicitação HTTP GET para a URL com um parâmetro de consulta '/swagger?format=json'.
Armazene o arquivo baixado no destino de saída; o padrão é '/docs/swagger'.
Agora que você tem o arquivo, envie-o como parte da sua solicitação de pull.
O script está totalmente documentado e pode ser encontrado aqui .
Você também pode executar o comando ' make openapi ' para gerar o arquivo e salvá-lo na pasta 'doc/swagger'. Adicionei este comando makefile porque os makefiles nos permitem usar um comando mais simples localmente no terminal do IDE e no pipeline CI/CD sem expor a implementação interna (o script Python), que podemos substituir e atualizar a qualquer momento; é apenas uma melhor experiência do usuário.
No projeto Cookbook, prefiro salvar a documentação JSON na pasta 'docs/swagger' para que ela possa ser carregada no site das páginas do GitHub do meu projeto . As páginas do GitHub são uma ótima maneira de permitir que os clientes visualizem suas APIs, pelo menos para projetos de código aberto.
Agora que temos a documentação em nosso repositório GitHub, podemos confirmá-la e gerar uma versão atualizada sempre que fizermos alterações na API.
Vamos ainda mais longe com duas automações cruciais.
Ações do GitHub e automação de CI/CD
Esta seção apresentará duas automações de CI/CD críticas para o processo de documentação do OpenAPI. Eu presumo que você pode gerar a documentação, seja no processo que apresentei ou de alguma outra forma.
Ambas as automações já fazem parte do pipeline de CI/CD do modelo de livro de receitas do AWS Lambda .
O código está sincronizado com a documentação
A primeira automação é crucial. Queremos garantir que nosso arquivo de documentação comprometido represente o verdadeiro estado da API e esteja de fato sincronizado com o código. Se enviarmos o arquivo de documentação aos clientes ou o publicarmos online, precisamos garantir que ele esteja sempre atualizado.
Nem sempre podemos esperar que os clientes usem o ponto de extremidade '/swagger' e, em alguns casos, podemos não querer expô-lo.
Atualmente, embora possamos gerar a documentação e confirmar o arquivo, os desenvolvedores precisam se lembrar de atualizar a documentação e executar o script apresentado na parte de automação acima. Se eles esquecerem, nosso arquivo confirmado estará fora de sincronia. Os clientes da API não apreciarão a documentação desalinhada e a frustração que vem com ela quando as chamadas da API não funcionam como esperado.
Podemos adicionar uma nova etapa ao nosso pipeline de CI/CD onde, como parte de uma solicitação de pull, validamos que a documentação confirmada está em sincronia com o status atual da API. Primeiro, implantaremos nosso aplicativo e, após a etapa de implantação do serviço , podemos executar essa verificação de validação. Se você se lembra, geramos a documentação baixando-a do endpoint '/swagger', então devemos implantar nosso serviço primeiro.
Vamos analisar uma ação do GitHub que resolve esse problema para nós.
É um passo simples que executa um comando makefile.
E aqui está a implementação do comando makefile no bash:
Na linha 6, usamos o script que apresentei no início do post para gerar um arquivo de documentação a partir do serviço implantado no pull request. Nós o salvamos como '.openapi_latest.json'.
Na linha 7, comparamos o arquivo confirmado (em './docs/swagger/) com o arquivo que acabamos de gerar. Se o desenvolvedor atualizou a API e esqueceu de atualizar a documentação (executando o comando makefile 'make openapi' que apresentei na seção anterior) nas linhas 10-13, falharemos na solicitação de pull.
Como você pode ver na linha 11, os desenvolvedores também podem executar 'make pr' antes de enviarem seu código. O comando executa e corrige automaticamente todos os linters, formatadores e geração de OpenAPI.
O makefile completo pode ser encontrado aqui .
Como você pode ver, é super simples, mas eficaz. Nós garantimos que a documentação esteja sempre em sincronia com a API que o código expõe.
Evitar alterações que quebrem a API
A segunda automação previne mudanças de quebra na sua API. Às vezes, os desenvolvedores cometem erros e fazem mudanças de quebra sem perceber o impacto em seus clientes.
Uma alteração drástica é uma alteração que pode exigir que você faça alterações em seu aplicativo para evitar interrupções em sua integração - Documentação da API do LinkedIn
As mudanças drásticas na API ocorrem de várias formas (conforme definido pela documentação da API do LinkedIn ) :
Alterações nas definições de permissão existentes
Remoção de um parâmetro permitido, campo de solicitação ou campo de resposta
Adição de um parâmetro obrigatório ou campo de solicitação sem valores padrão
Alterações na funcionalidade pretendida de um endpoint. Por exemplo, se uma solicitação DELETE foi usada anteriormente para arquivar o recurso, mas agora exclui o recurso permanentemente.
Introdução de uma nova validação
Ao lidar com mudanças na API, devemos sempre nos esforçar para fazê-las de maneira ininterrupta, e há muitas maneiras de fazer isso, mas deixo isso para outro post.
No entanto, não quero deixar nada ao acaso e espero que o revisor de código entenda que as alterações de código no PR (pull request) são alterações drásticas.
Quero que o PR falhe automaticamente se houver uma alteração significativa.
Agora que temos a documentação da API como parte do PR, a validamos e garantimos que ela esteja sincronizada com o código do serviço, a verificação de alterações significativas se torna muito mais acessível.
Após a implantação, adicionaremos uma nova etapa ao pipeline de CI/CD do nosso PR.
Usaremos uma ação de código aberto do GitHub, oasdiff-action , baseada na ferramenta ' oasdiff '.
A ferramenta aceita dois arquivos JSON OpenAPI, base e "new" (revisão), e verifica se há diferenças. Se encontrar diferenças, ela verifica se essas diferenças (mudanças) entre as APIs são mudanças de quebra. Caso sejam, o pipeline falha. É simples assim.
Vamos dar uma olhada na definição:
Comparamos o arquivo openapi.json na pasta './docs/swagger' que contém nossas alterações na documentação com o arquivo atualmente mesclado na ramificação principal do repositório GitHub.
Vamos testar a utilidade.
Digamos que adicionamos um novo parâmetro padrão ao nosso esquema de entrada 'CreateOrderRequest': 'new_order_item_count.'
Esta é uma mudança de quebra clássica. Uma maneira melhor é definir um valor padrão para 'new_order_item_count' ou introduzir uma API v2 onde este campo seja obrigatório.
O desenvolvedor gerará a nova documentação, e a ação do GitHub verificará se há alterações significativas no código mesclado atual.
Agora, quando esse PR for executado, obteremos uma falha com as seguintes informações:
O erro está correto; adicionamos uma nova propriedade de solicitação obrigatória, que falhou como esperado; nossa documentação e usuários estão salvos de uma alteração drástica!
Obrigado, Afik Grinstein , por me apresentar este utilitário.
Resumo
Isso conclui o segundo post da minha série de documentação sobre OpenAPI e API sem servidor.
Criamos um script que gera documentação OpenAPI a partir do código dos nossos manipuladores Lambda e o exporta; validamos que ele está sincronizado com o código e garantimos que ele não traz nenhuma alteração que interrompa a API.