{"id":2789,"date":"2014-09-25T12:36:45","date_gmt":"2014-09-25T15:36:45","guid":{"rendered":"http:\/\/blog.dialhost.com.br\/?p=2789"},"modified":"2014-09-25T12:36:45","modified_gmt":"2014-09-25T15:36:45","slug":"review-apiary-fazendo-muito-mais-que-apenas-documentar","status":"publish","type":"post","link":"https:\/\/www.dialhost.com.br\/blog\/review-apiary-fazendo-muito-mais-que-apenas-documentar\/","title":{"rendered":"Review: Apiary \u2013 Fazendo muito mais que apenas documentar"},"content":{"rendered":"
\"apiary\"<\/a>
P\u00e1gina do Apiary<\/figcaption><\/figure>\n

H\u00e1 algum tempo, venho trabalhando diretamente com APIs de diversos tipos. Tanto APIs p\u00fablicas abertas, quanto fechadas. Em partes, meu trabalho est\u00e1 na cria\u00e7\u00e3o de documenta\u00e7\u00f5es, SDKs e artigos t\u00e9cnicos para utiliza\u00e7\u00e3o e consumo.<\/p>\n

Uma das maiores dificuldades na cria\u00e7\u00e3o de documenta\u00e7\u00e3o de API, al\u00e9m, claro, da manuten\u00e7\u00e3o, \u00e9 a ilustra\u00e7\u00e3o de sua utiliza\u00e7\u00e3o para o desenvolvedor que est\u00e1 tento o primeiro contato com ela. Ao iniciar a integra\u00e7\u00e3o, \u00e9 natural que o desenvolvedor precise, por exemplo, saber como suas requisi\u00e7\u00f5es HTTP est\u00e3o sendo recebidas pela API e qual est\u00e1 sendo a resposta da API, para aquela requisi\u00e7\u00e3o espec\u00edfica.<\/p>\n

Ilustrar o recebimento da requisi\u00e7\u00e3o e a resposta para essa requisi\u00e7\u00e3o, em uma documenta\u00e7\u00e3o, n\u00e3o \u00e9 uma tarefa simples. E \u00e9 justamente nesse ponto que o Apiary<\/a> mostra sua for\u00e7a.<\/p>\n

Primeiro contato<\/strong><\/p>\n

Eu j\u00e1 tinha uma conta no Apiary h\u00e1 algum tempo, mas apenas recentemente fui realmente utiliz\u00e1-lo para um caso de uso em produ\u00e7\u00e3o. A interface do Apiary \u00e9 bastante simples e a organiza\u00e7\u00e3o facilita sua utiliza\u00e7\u00e3o:<\/p>\n

\"ri01\"<\/a>
\nDe um lado, temos o conte\u00fado da API. A separa\u00e7\u00e3o por recurso\/verbo HTTP simplifica tanto a cria\u00e7\u00e3o da documenta\u00e7\u00e3o para aquele recurso\/verbo, quanto o entendimento daquilo que est\u00e1 sendo documentado. Algumas documenta\u00e7\u00f5es podem ter diversos recursos e o ToC no lado direito facilita a navega\u00e7\u00e3o entre os recursos.<\/p>\n

Documenta\u00e7\u00e3o facilitada<\/strong><\/p>\n

A ferramenta j\u00e1 seria excelente, por cumprir muito bem seu prop\u00f3sito de documentar. Mas como manter a documenta\u00e7\u00e3o \u00e9 uma tarefa, talvez, ainda mais complexa que escrever a documenta\u00e7\u00e3o, o Apiary oferece a integra\u00e7\u00e3o com um reposit\u00f3rio no Github.<\/p>\n

Isso significa que podemos escrever toda a documenta\u00e7\u00e3o em Markdown e, ao fazer push para o reposit\u00f3rio, a documenta\u00e7\u00e3o no Apiary \u00e9 atualizada automaticamente.<\/p>\n

Ambiente de testes<\/strong><\/p>\n

Pronto, escrevi a documenta\u00e7\u00e3o da minha API. E agora?<\/p>\n

Apesar de o Apiary ter a documenta\u00e7\u00e3o como foco, o ponto mais forte, na minha opini\u00e3o, \u00e9 o Mock Server. Ao definir os recursos da API e os verbos, podemos tamb\u00e9m definir o que \u00e9 esperado para determinada requisi\u00e7\u00e3o HTTP e qual ser\u00e1 a resposta, se a requisi\u00e7\u00e3o for feita corretamente.<\/p>\n

O Mock Server \u00e9 composto por dois ambientes distintos:<\/p>\n