Stoplight/Prism-CLI - Acelerando o desenvolvimento e aumentando a integração
Tags: api, documentation, frontend, backend
Published: 2021-02-25 19:29:22

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_.

![Prism exemplo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hbh6zs1f1amp3ykh0w88.png)

# Sumário
1. [Instalação do @stoplight/prism-cli](#instalação-do-@stoplight/prism-cli)
2. [Código _back-end_ & _OpenAPI Documentation_](#código-back-end-&-openapi-documentation)
3. [Prism _Mock Server_](#prism-mock-server)
4. [Prism _Proxy Server_](#prism-proxy-server)
5. [Conclusão](#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:

```bash
# 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](https://github.com/wizsolucoes/api-wiz-template) 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_).

![Tags XML e Annotations para uma rota da API](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/91wdeo6l9sw2p2s2iwpz.png)
Figura 1 - _Tags_ XML e _Annotations_ para uma rota da API.

![Documentação gerada pelas tags XML e Annotations no código back-end](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/81tw2x1wcwaz1upjzykh.png)
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.

![Exemplo de resposta genérica gerada pelo OpenAPI](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yh0m2peqil8seq5chlpu.png)
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.

![Exemplos de tags para documentação no OpenAPI](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rgqqe3usa9d5mzsh7bnk.png)
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:

```bash
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”:

```bash
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:

```bash
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.