Análise estática de API Specification
Usando o Spectral Linter para melhorar a qualidade de especificações de API
"A baixa qualidade da documentação de APIs é o principal obstáculo para seu consumo e para seus testes." Reis, 2020
API Specifications (também chamadas de API Specs ou especificações de API) são um dos principais documentos de uma API. Por isso, é crucial assegurar que elas possuem informações corretas sobre a API, e que essas informações são úteis e completas.
Atentar-se à qualidade da especificação da API é um hábito que todo o time deve ter, e que deve ser incorporado à estratégia de qualidade. Frequentemente essa documentação é negligenciada, trazendo inúmeros prejuízos na adoção dessas APIs (Reis, 2020).
Uma das formas de aumentar a qualidade das API Specs é se atentar para sua formatação. Entretanto, os formatos de API Specs, como o OpenAPI, podem ser permissivos e vagos. Ou seja, é possível criar API Specs cuja formatação é válida, mas cujos conteúdos não são muito úteis. Isso acaba comprometendo a experiência das pessoas usuárias.
Por esta razão, o uso de análise estática para averiguar a qualidade dessa especificação é de grande ajuda. O uso de linters de API Specs ajuda a identificar erros e más práticas ainda na fase de desenvolvimento. Neste artigo, iremos discutir como o uso de análise estática, especificamente o uso do Spectral Linter, pode contribuir na melhoria da qualidade de APIs Specs.
Este artigo possui duas partes:
Parte 1: Conceitos fundamentais
Parte 2: Adotando o Spectral
PARTE 1: Conceitos fundamentais
O que é uma API Spec/Specification?
Para que aplicações se comuniquem, deve haver um vocabulário em comum. Não apenas existe um padrão para implementar APIs como o REST, como também existe um padrão para documentá-las corretamente.
Uma API só tem valor se estiver acessível para ser integrada imediatamente com outras aplicações. E para isso, é necessária uma documentação clara. Para padronizar o vocabulário em torno das APIs criaram-se as Especificações de API (ou API Specification, ou API Spec).
Uma API Spec contém (SmartBear, 2021):
- Endpoints disponíveis, e suas respectivas operações suportadas (ex: GET, POST, DELETE, PUT);
- Parâmetros de operação de entrada (request) e retorno (response) para cada operação;
- Métodos de autenticação (ex: OAuth 2.0);
- Informações de contato, licença, termos de uso e outras informações.
Em suma, a API Spec é um arquivo, normalmente em formato JSON ou YAML, usado para descrever, produzir, consumir e visualizar serviços de uma API. Abaixo um exemplo de API Spec no formato JSON que utiliza OpenAPI:
O que é a OpenAPI Specification?
A especificação OpenAPI é um tipo de API Spec, assim como o RAML e a API Blueprint. A OpenAPI Spec pode ser escrita manualmente ou gerada automaticamente a partir de anotações no próprio código-fonte.
Swagger vs OpenAPI
Em 2015, a SmartBear lançou a OpenAPI Initiative, com a participação de grandes empresas como Atlassian, eBay, Google, Paypal, Microsoft, Red Hat, SmartBear, e muitas outras, com patrocínio da Linux Foundation. A especificação Swagger foi adotada por essa iniciativa e renomeada como OpenAPI Specification (Anthony, 2021).
O termo “Swagger” ainda é utilizado, e é comum as pessoas não saberem quando utilizá-lo ao invés do termo “OpenApi”. Então perceba a diferença:
- OpenAPI: é a especificação em si;
- Swagger: conjunto de ferramentas usadas na implementação de especificações OpenAPI, como, por exemplo, Swagger Editor, Swagger UI, Swagger Codegen e Swagger Inspector.
Ler um JSON ou YAML não é tão amigável assim
A ideia de existir API Specs também é para que ferramentas possam transformar estas especificações em uma interface. Um exemplo é o Swagger UI que gera automaticamente uma interface a partir de uma OpenAPI Spec. Nesta interface, é possível visualizar e interagir com os recursos da API. Logo, ela permite que seus usuários experimentem as chamadas de API diretamente no navegador sem precisar de novas implementações. Abaixo um exemplo no Swagger UI:
O que é análise estática?
A análise estática é um tipo de teste caixa branca realizado por ferramentas com o objetivo de destacar possíveis vulnerabilidades no código-fonte estático, ou seja, sem executá-lo, usando técnicas como análise de contaminação e de fluxo de dados (OWASP, 2021).
A análise estática é uma ferramenta poderosa para garantir a qualidade e robustez do software. Segundo a DeepSource Corp, alguns problemas que essas ferramentas apontam são:
- Vulnerabilidades de segurança em potencial
- Riscos de defeitos
- Anti-padrões
- Falta de adesão a regras ou convenções de estilo de código
- Problemas de desempenho
- Código morto (dead code) ou código não usado
O que significa linter?
Linter é a forma mais básica de ferramenta de análise estática. Ele verifica de forma automática o código-fonte em busca de erros programáticos e estilísticos. O uso de linters durante o desenvolvimento acelera o desenvolvimento e reduz custos, encontrando erros mais cedo (Bellairs, 2021).
Existem diversos linters disponíveis para várias linguagens de programação, como, por exemplo, o ESLint e o Spectral Lint. Algumas verificações que eles fazem são:
- Erros de sintaxe
- Aderência aos padrões de código
- Code smells
- Análise de segurança
Porque usar um linter de API Spec?
Você precisa de um linter de API Spec se você responder “Sim” a uma dessas perguntas:
- Você tem uma lista de regras de escrita de API Specs, mas ninguém segue?
- Seu time não possui regras de escrita de API Specs, e você não sabe por onde começar?
- Não sabe com facilidade quais ou quantas regras suas API Spec está quebrando?
- Não sabe a severidade das regras que estão sendo quebradas?
- Seu time mantém várias APIs simultaneamente, e a API Spec delas é despadronizada em formato e/ou conteúdo?
PARTE 2: Adotando o Spectral
Spectral
Spectral é um linter de API Specs nos formatos JSON e YAML. É uma ferramenta open source que ajuda a construir uma estrutura consistente da API Spec desde o início do desenvolvimento. Seus principais benefícios são:
- Promove uniformidade entre diferentes arquivos;
- Pode ser utilizado em especificações do tipo OpenAPI (2.0 e 3.0), AsyncAPI e RAML;
- Apresenta mensagens de erros e warnings amigáveis, de simples compreensão;
- É customizável: se houver uma regra que não te agrada é possível editá-la ou desativá-la com facilidade;
- Pode ser integrada à pipeline;
- Fácil instalação.
Como instalar o Spectral
Há quatro opções:
Mais detalhes para a instalação neste link.
Instalando o Spectral no VS Code
Clique no link abaixo para baixar o Spectral.
Após instalar, você pode configurar esta extensão. Vá até: Extensions → Spectral → ⚙️ → Extension Settings. É possível configurar, por exemplo, qual é a localização do arquivo ruleset. Se este arquivo não for indicado, o default é o arquivo .spectral.ymlou .spectral.jsonlocalizado na mesma pasta do arquivo que estiver sendo validado.
Executando o Spectral no Visual Studio
Basta abrir o terminal do Visual Studio, na aba Problems:
Lembre-se que integrar uma ferramenta de análise estática, como o Spectral na IDE, é uma das boas práticas defendidas neste artigo sobre Shift-Left Testing.
Executando o Spectral no terminal
Ao instalar o Spectral, ele já vem com regras default. Para executar com estas regras, basta executar o seguinte comando:
spectral lint petstore.yaml
Para executar com regras customizadas, indique qual é o arquivo de configuração do Spectral que deseja utilizar:
spectral lint petstore.yaml --ruleset .custom-rules.ymlPara executar o Spectral para múltiplos arquivos, indique cada um deles no mesmo comando:
spectral lint petstore.yaml petstore-expanded.json
Executando o Spectral no Stoplight
Visite este link e acesse: Start Linting for free → Cadastre-se → Go to the company workspace → Add your first project → Import file. Importe o arquivo que deseja testar. Após carregado, clique no nome do arquivo e depois em Problems. O Spectral irá apontar todos os problemas que foram encontrados no canto direito da tela (como na imagem abaixo). Clique no erro que deseja explorar e será redirecionado para a respectiva linha onde o erro ocorreu.
Para identificar qual regra do Spectral foi quebrada, clique no respectivo problema, como abaixo:
Como customizar o Spectral
Conforme a documentação oficial da ferramenta, é possível alterar as regras default do Spectral, e até mesmo implementar novas. Digamos que há uma regra que não faz muito sentido no seu contexto, então você pode desativá-la, como abaixo:
Neste repositório do Github existem diversas regras já customizadas, bastando você escolher quais estão aderentes à sua necessidade. Um dos arquivos mais interessantes desse repositório é o apisyouwonthate.yml, cujas regras que apresenta são derivadas do blog e do livro APIs You Won’t Hate.
Uma boa documentação de uma API só é possível quando o seu design segue as regras fundamentais da arquitetura como, por exemplo, o padrão REST. O livro Rest API Design Rulebook: Designing Consistent Restful Web Service Interfaces compila as boas práticas desta arquitetura em um conjunto de regras a serem seguidas.
Você pode se inspirar nas regras desse livro para criar regras customizadas no Spectral e checar se sua API está seguindo essas boas práticas.
Conclusão
Além de desenvolver uma API que siga corretamente padrões de arquitetura, devemos monitorar e advogar pela qualidade da documentação das APIs, a começar pelas API Specs. Seja usado o Spectral ou qualquer outro linter de API Spec, adicione formalidade à este monitoramento ao definir exatamente quais regras devem ser seguidas e ao integrá-lo na pipeline.
Referências
- Static Code Analysis — https://owasp.org/www-community/controls/Static_Code_Analysis
- What Is Lint Code? And Why Is Linting Important? https://www.perforce.com/blog/qac/what-lint-code-and-why-linting-important
- What is the difference between Swagger and OpenAPI? — https://nordicapis.com/whats-the-difference-between-swagger-and-openapi/
Agradecimentos
Gabriel Santos, Rafael Peixoto, Rodrigo Fragoso
