Your Web News in One Place

Help Webnuz

Referal links:

Sign up for GreenGeeks web hosting
April 14, 2021 08:46 pm GMT

Documentando minha API 1 API Blueprint Aglio

Mexer num projeto cuja API no tem documentao um sofrimento ter que vasculhar no cdigo do projetos os endpoints e entender o que possvel fazer com cada um deles um trabalho desnecessrio, e seria resolvido de forma simples com uma bendita documentao :(.

J diz a frase:

Uma API documentada uma API feliz

Eis que chega a minha hora de fazer um projeto novo, e no posso cair na mesma mancada de deixar o cdigo ser a fonte de entendimento da API.

Como especificao para a construo dessa documentao, optei pela API Blueprint. Criada pela Apiary(Oracle), tem a vantagem de ser escrita utilizando Markdown, facilitando a leitura.

Comeando

Seguindo o padro da API Blueprint, podemos escrever nossa documentao em Markdown ou com a extenso .apib. Optei pela segunda, j que possvel encontrar extenses para meu editor de texto.

FORMAT: 1AHOST: http://api.meninogaimeiro.com.br# API do Menino GaimeiroUma API pra voc gerenciar a sua carteirinha xD.# Group Games## Games [/games]### Criar games [POST]+ Request Criar um game    + Headers            Accept: application/json            Content-Type: application/json    + Attributes        + name (required)+ Response 201 (application/json)    + Attributes        + id: 1 (number) - ID do game        + name: Desperados 3 (string) - Nome do game+ Response 400 (application/json)    + Attributes        + status_code: 400 (number) - Status code da Request        + errors (array) - Objeto de erros            + (object)                + parameter_name: name (string) - Nome do parmetro                + message: field is required (string) - Tipo do erro

O exemplo acima faz o seguinte:

  • Seta a url da api parahttp://api.meninogaimeiro.com.br;
  • Cria um grupo de rotas chamada*games*;
  • Cria um grupo de rotas*Games /games.Nesse meu exemplo ficou repetido, mas poderia existir junto com essa rota o*Platforms /games/platforms;
  • Crio uma request informando seus headers e seus atributos;
  • Crio uma response informando seus status codes e seus payloads

Para ver como essa documentao renderizada usando o Apiary,clique aqui.

Gerando a documentao

A API Blueprint apenas uma especificao, no uma tecnologia. Para gerar uma documentao em meu projeto Node, acabei por utilizar a engine Aglio, que ser responsvel por interpretar os arquivos nesse formato e renderizar a documentao formatada.

Para isso, faa:

  • npm install -g aglio
  • aglio -i api.apib theme-template triple -s

Esse ltimo comando ler o arquivo*api.apib*, gerando um template de 3 colunas em um servidor.

Eis que o resultado ser algo como mostrado na imagem abaixo:

alt text

Pronto! Com isso j posso dar continuidade na documentao da API :).


Original Link: https://dev.to/allangrds/documentando-minha-api-1-api-blueprint-aglio-48h2

Share this article:    Share on Facebook
View Full Article

Dev To

An online community for sharing and discovering great ideas, having debates, and making friends

More About this Source Visit Dev To