Ao desenvolver novas APIs, muitas vezes os desenvolvedores (devs) front-end precisam mockar dados para criar e demonstrar os layouts que estão desenvolvendo. É uma atividade que demanda tempo e, eventualmente, o código será jogado fora. No back-end, as features podem demorar algum tempo para estarem disponíveis e, em caso de mudanças, o dev terá de alterar o código, atualizar os testes, realizar uma nova build e um novo deploy, atividades que demandam tempo. Como podemos otimizar as tarefas do back-end e front-end para que não haja código mockado e novo ciclo de dev-build-deploy? Podemos utilizar a ferramenta Stoplight/Prism-CLI.

Prism permite que devs criem mocks da API com uma base mínima de código no back-end, fazendo com que não seja necessária a criação de mocks – que serão, eventualmente, descartados – no front-end. Ainda, torna possível testar o contrato da API, por meio de um proxy, auxiliando na diminuição de erros após mudanças no código. Por fim, como a ferramenta usa o OpenAPI como base para criação dos mocks e proxies, sua utilização auxilia na criação de documentações mais robustas para as APIs desenvolvidas. Este artigo abordará como utilizar a ferramenta em seus dois modos – mock e proxy – para auxiliar, acelerar e integrar o desenvolvimento front-end e back-end.

Sumário

1. Instalação do @stoplight/prism-cli
2. Código back-end & OpenAPI Documentation
3. Prism Mock Server
4. Prism Proxy Server
5. Conclusão

Instalação do @stoplight/prism-cli

Antes de mais nada, precisamos instalar a ferramenta Prism em nosso ambiente de desenvolvimento. A documentação prevê três formas de instalação, mas por motivos de simplicidade, abordaremos apenas o primeiro, que utiliza o NPM para realizar a instalação. Dessa forma, instale a ferramenta utilizando o comando:

# Usando NPM
npm i -g @stoplight/prism-cli

# Usando Yarn
yarn add global @stoplight/prism-cli

Código back-end & OpenAPI Documentation

Com o Prism instalado, podemos iniciar o código back-end. O template de APIs da Wiz já traz um exemplo básico de arquitetura de desenvolvimento de uma API e possui o OpenAPI instalado por default.

As rotas do template possuem algumas tags XML e Annotations, que formarão o JSON responsável por gerar a documentação da API. Na Figura 1, a rota apresenta uma descrição (summary), três códigos de resposta (response) e três schemas para os códigos de respostas gerados (ProducesResponseType).

Figura 1 - Tags XML e Annotations para uma rota da API.

Figura 2 - Documentação gerada pelas tags XML e Annotations no código back-end.

Se pararmos aqui, os exemplos de requisição e resposta, gerados pelo OpenAPI, serão genéricos, como visto na Figura 3.

Figura 3 - Exemplo de resposta genérica gerada pelo OpenAPI.

O Prism é capaz de gerar informações aleatórias para compor as respostas, no entanto como veremos mais adiante, é possível ter maior controle sobre o conteúdo das respostas e, por consequência, definir exemplos que documentarão melhor a API em desenvolvimento.

Para isso, adicionaremos tags XML e Annotations nas ViewModels da API e, caso não existam ViewModels específicas para erros, criaremos classes de exemplo para compor a documentação. A Figura 4 demonstra algumas das tags e Annotations utilizadas para melhor documentar a API. É importante ressaltar que, no caso da Annotation JsonSchemaExtensionData, é necessária a instalação do pacote NjsonSchema.Annotations, que permite adicionar informações que não seriam identificadas pelo OpenAPI.

Ao analisar a Figura 4, as tags example e minimum provavelmente são familiares, pois estão previstas na especificação do OpenAPI. Mas e a tag x-faker?

Prism Mock Server

Como dito anteriormente, o Prism é capaz de gerar mocks de respostas para as requisições feitas ao servidor gerado a partir da descrição do OpenAPI. Essas respostas podem ser estáticas ou dinâmicas. Vamos começar pelas respostas estáticas.

Figura 4 - Exemplos de tags para documentação no OpenAPI.

As respostas estáticas são produzidas a partir dos exemplos informados nas ViewModels da API e serão o default ao iniciar o servidor por meio do comando:

prism mock http://localhost:5001/swagger/v1/swagger.json

## Ou

prism mock path/to/descriptor.json

Ao iniciar o mock server dessa maneira, todas as repostas serão baseadas nos exemplos fornecidos. Caso não haja um exemplo, o Prism gera respostas aleatórias com base nos tipos esperados.

No entanto, a utilização das respostas estáticas pode gerar um viés no front-end, uma vez que as respostas, em um cenário real, são variadas. Então, como podemos gerar respostas aleatórias, mas com algum controle sobre seu conteúdo? É aqui que a tag x-faker vai nos ajudar.

Por baixo dos panos, o Prism utiliza a biblioteca Faker.js para gerar os dados de forma aleatória e, acessando a documentação da biblioteca, vemos que existem dezenas de métodos capazes de gerar respostas aleatórias para diversos contextos. Assim, podemos utilizar a tag x-faker, combinada com os métodos disponibilizados pela API, para imprimir contexto nas respostas. Na Figura 4, por exemplo, o “CEP” é gerado com base no método address.zipCode e, portanto, toda resposta não estática vai gerar um zip code aleatório.

Mas ainda fica uma dúvida: caso exista um exemplo, como o mock server pode gerar respostas dinâmicas? Para isso, basta iniciar o mock server com a flag “-d” ou “--dynamic”:

prism mock -d http://localhost:5001/swagger/v1/swagger.json

Ainda, é possível determinar que apenas uma rota específica gere respostas estáticas ou dinâmicas. Para isso, basta passar a utilizar o header “Prefer dynamic=true/false” em suas requisições. O mesmo header pode ser utilizado mais de uma vez e pode ajudar a controlar, também, o código da resposta gerada. Por exemplo, caso o front-end queira testar um cenário de erro na resposta da API, ele pode criar uma requisição com contrato inválido (faltando um campo obrigatório, por exemplo) ou pode utilizar o header “Prefer code=400” para gerar uma resposta com código 400 (Bad Request) por parte do mock server. Para mais exemplos sobre o header, utilize a documentação do Prism.

Prism Proxy Server

Utilizando o mock server, os devs front-end podem ir desenvolvendo os sites sem a necessidade de um back-end funcional, sendo necessário trocar apenas o endereço base das requisições pelo endereço da API funcional, uma vez que esta esteja disponível (i.e. trocar http://localhost:4010/api/vX/ por https://<projeto>-hml-api.azurewebsites.net/api/vX).

Apesar disso, pequenas mudanças ou erros podem ter ocorrido – tanto no front, quanto no back – e as requisições ou os contratos não estarem de acordo com o esperado. Para testar os contratos, o Prism dispõe de um proxy server.

O proxy server utiliza um descritor do OpenAPI e o endereço da API para validar os contratos de requisição e resposta. Dessa maneira, o usuário pode realizar chamadas à API e verificar se todas as requisições feitas e as respostas geradas batem com o que está definido no descritor, garantido que, uma vez que a API vá para produção, front e back não possuam erros de contrato. O proxy server pode ser iniciado pelo comando:

prism proxy path/to/descriptor.json https://<projeto>-hml-api.azurewebsites.net

Para mais informações sobre o proxy server, acesse a documentação do Prism.

Conclusão

A ferramenta Prism server para auxiliar a abordagem “design-first” para o desenvolvimento de APIs por meio do mock e, uma vez que todas as informações e preparativos estejam nas mãos do time de back-end, o proxy permite testar os contratos criados entre front e back.
Sendo assim, o Prism pode auxiliar na integração entre devs front e back, que terão de chegar a um consenso sobre os contratos, permite que o front desenvolva sem a necessidade de uma API e auxilia o back em uma melhor documentação da API em desenvolvimento.