An Interest In:
Web News this Week
- March 19, 2024
- March 18, 2024
- March 17, 2024
- March 16, 2024
- March 15, 2024
- March 14, 2024
- March 13, 2024
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:
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
Dev To
An online community for sharing and discovering great ideas, having debates, and making friendsMore About this Source Visit Dev To