Como validar seu Guideline de API na pipeline do CI

Partindo do ponto que estamos seguindo a metodologia de design-first de API, a especificação OpenAPI é o documento mais vivo do contrato de API, com o objetivo de contemplar todos os detalhes de como aquela API funciona.

Segundo a OpenAPI Specification, temos algumas “regras” estabelecidas pela própria comunidade que adota padrões e boas práticas no desenvolvimento de uma interface de API.

Desenhe primeiro sua interface de API, antes de desenvolver

If you asked 100 developers which naming conventions to use where in an API spec, you’ll either get 100 answers or an all-out brawl. To save this from happening, most API teams that grow beyond a handful of developers will implement a style guide.

Por que os Guidelines são importantes?

Um Guideline de API garante que todos na equipe sigam os padrões básicos de design de API, deixando as interfaces de API mais consistentes e podendo automatizar e validar as especificações adotadas.

A equipe também pode adotar regras particulares que façam sentido para o seu negócio.

Defina a governança, crie consistência e melhore seus produtos de API.

Qual ferramenta vamos usar para validar o OpenAPI?

Neste exemplo vamos utilizar o spectral. Spectral é um projeto open source da Stoplight que analisa arquivos JSON/YAML validando se está no padrão Guideline adotado.

Foto de Negative Space/Pexels

Spectral tem as seguintes funcionalidades:

• Regras personalizados: Criar regras personalizadas para objetos JSON ou YAML
• Regras prontas para uso: Valida e analisa OpenAPI v2 e v3.x e Documentos AsyncAPI
• Guias de estilo da API: Guias de estilo de API automatizados usando conjuntos de regras melhoram a consistência em todas as suas APIs
• Funções prontas para uso: Conjunto de funções integradas para ajudar a criar regras personalizadas. As funções incluem verificações de padrões, verificações de parâmetros, ordenação alfabética, um número especificado de caracteres, verificação de chaves de objetos estejam presentes, etc.
• Funções personalizadas: Crie funções personalizadas para casos de uso avançados

Para mais detalhes acesse o GitHub do projeto stoplightio/spectral

Como fazer uma validação usando o Spectral?

Como pré-requisito, é necessário ter apenas docker instalado na máquina.

Vamos precisar criar o arquivo spectral.yaml com as regras que serão analisadas. Esse arquivo irá considerar as regras do OAS e uma regra customizada para verificar se as tags possuem descrição, o arquivo de configuração ficará assim:

extends: spectral:oas
rules:
  tag-description:
    description: Please provide a description for each tag.
    given: $.tags[*]
    then:
      field: description
      function: truthy

Para rodar uma validação básica de um arquivo OpenAPI, considerando as regras estabelecidas no arquivo spectral.yaml, execute o seguinte comando no seu terminal:

docker run --rm -it -v $(pwd):/tmp stoplight/spectral lint \
  --ruleset "/tmp/.spectral.yaml" \
  "/tmp/openapi.yaml"

A saída do console será algo assim:

2:6    warning  info-contact           Info object must have "contact" object.
2:6    warning  info-description       Info "description" must be present and non-empty string.
11:9   warning  operation-description  Operation "description" must be present and non-empty string.
15:11  warning  operation-tag-defined  Operation tags must be defined in global tags.
42:10  warning  operation-description  Operation "description" must be present and non-empty string.
46:11  warning  operation-tag-defined  Operation tags must be defined in global tags.
57:9   warning  operation-description  Operation "description" must be present and non-empty string.
61:11  warning  operation-tag-defined  Operation tags must be defined in global tags.

✖ 8 problems (0 errors, 8 warnings, 0 infos, 0 hints)

Com isso, conseguimos ter uma análise do arquivo OpenAPI verificando-o se está de acordo com o Guidelines estabelecido pelo time.

Este exemplo está disponível no GitHub para facilitar o teste. Clone, execute e teste na sua máquina ;)

• Meu perfil na rede: https://github.com/rafaelbmateus
• Exemplo: https://github.com/rafaelbmateus/stoplight-spectral-cli

Por que validar o guideline de API na pipeline?

Uma maneira importante de impor a consistência do estilo da API é usar ferramentas automatizadas para garantir que o mesmo padrão seja aplicado de maneira escalável em todas as suas APIs.

Em vez de implementar isso manualmente, você pode usar ferramentas para aplicar automaticamente as diretrizes padrão da API, que são um conjunto de regras objetivas que definem como a API deve operar.

Podemos considerar essa validação na primeira camada como uma ferramenta de análise de código estática como um linter.

Criei um job na pipeline do projeto para fazer essa validação, desse modo não terá o risco de algum endpoint de API não seguir o padrão desejado.

No repositório de exemplo a pipeline está sendo acionada pelo workflow do github actions: https://github.com/rafaelbmateus/stoplight-spectral-cli/actions

Referências

https://github.com/OAI/OpenAPI-Specification
https://github.com/stoplightio/spectral
https://stoplight.io/api-style-guides-guidelines-and-best-practices

Curtiu o conteúdo? Não se esqueça de deixar seus comentários, dúvidas e compartilhar esse post nas suas redes.

A Neoway desenvolve soluções de Big Data Analytics e Inteligência Artificial que geram precisão para a tomada de decisão e produtividade para os processos de marketing, compliance, prevenção contra fraudes, análises jurídicas, gestão de crédito, entre outros.

Estamos contratando: para saber mais sobre as vagas disponíveis, visite nosso perfil oficial na Gupy.