{"id":10597,"date":"2020-07-03T12:19:23","date_gmt":"2020-07-03T15:19:23","guid":{"rendered":"https:\/\/enotas.com.br\/blog\/?p=10597"},"modified":"2023-01-25T14:30:01","modified_gmt":"2023-01-25T17:30:01","slug":"documentar-uma-api","status":"publish","type":"post","link":"https:\/\/enotas.com.br\/blog\/documentar-uma-api\/","title":{"rendered":"Um Guia de como documentar uma API, com boas pr\u00e1ticas!"},"content":{"rendered":"<p dir=\"ltr\"><strong>Acompanhe o nosso guia e descubra a import\u00e2ncia de documentar uma API e tenha acesso a boas pr\u00e1ticas para realizar essa atividade de forma eficiente!<\/strong><\/p>\n<p dir=\"ltr\">API&#8217;s vem da abrevia\u00e7\u00e3o do termo &#8220;Application Programming Interface&#8221; e, como o pr\u00f3prio nome diz, com elas, \u00e9 poss\u00edvel criar interfaces para que sejam feitas integra\u00e7\u00f5es entre um ou mais sistemas.<\/p>\n<p dir=\"ltr\">Por meio das API&#8217;s, dois sistemas escritos em diferentes linguagens conseguem trocar informa\u00e7\u00f5es com facilidade.<\/p>\n<p dir=\"ltr\">Nesse cen\u00e1rio, um aspecto importante a ser levado em considera\u00e7\u00e3o \u00e9 a <strong>documenta\u00e7\u00e3o de API<\/strong>.<\/p>\n<p dir=\"ltr\">A documenta\u00e7\u00e3o permite que desenvolvedores tenham uma vis\u00e3o mais clara do seu produto e de como o seu c\u00f3digo pode funcionar em conjunto com o software deles.<\/p>\n<p dir=\"ltr\">Neste artigo, trouxemos algumas dicas importantes para te ajudar ao escrever a sua documenta\u00e7\u00e3o de API.&nbsp;<\/p>\n<p dir=\"ltr\">Al\u00e9m disso, abordaremos os principais problemas a serem considerados ao projetar sua pr\u00f3pria documenta\u00e7\u00e3o, independentemente da maneira que voc\u00ea distribua o seu aplicativo.<\/p>\n<p dir=\"ltr\">Quer saber como melhorar\/criar a documenta\u00e7\u00e3o de uma API? Acompanhe o nosso post!<\/p>\n<h2 dir=\"ltr\" id=\"indice-0\" data-indice=\"0\" data-viewport=\"indice\">Por que e como documentar uma API?<\/h2>\n<p dir=\"ltr\">A documenta\u00e7\u00e3o de uma API \u00e9 uma entrega t\u00e9cnica de conte\u00fado, contendo instru\u00e7\u00f5es sobre como usar e integrar efetivamente a solu\u00e7\u00e3o.<\/p>\n<p dir=\"ltr\">\u00c9 um manual de refer\u00eancia resumido que cont\u00e9m todas as informa\u00e7\u00f5es necess\u00e1rias para trabalhar com a API, com detalhes sobre:&nbsp;<\/p>\n<ul>\n<li dir=\"ltr\">fun\u00e7\u00f5es;&nbsp;<\/li>\n<li dir=\"ltr\">classes;&nbsp;<\/li>\n<li dir=\"ltr\">tipos de retorno;&nbsp;<\/li>\n<li dir=\"ltr\">argumentos;<\/li>\n<li dir=\"ltr\">tutoriais de exemplos.<\/li>\n<\/ul>\n<p dir=\"ltr\">Tradicionalmente, a documenta\u00e7\u00e3o de uma API \u00e9 feita usando exemplos pr\u00e1ticos que sejam facilmente identificados.<\/p>\n<p dir=\"ltr\">Ao se deparar com a API, o usu\u00e1rio vai procurar informa\u00e7\u00f5es acess\u00edveis, claras e completas para que possa integrar algum sistema.<\/p>\n<p dir=\"ltr\">No desenvolvimento da documenta\u00e7\u00e3o n\u00e3o se pode pular etapas, pois esse \u00e9 o caminho para aumentar as integra\u00e7\u00f5es e o n\u00famero de usu\u00e1rios, garantindo assim o sucesso. \u00c9 ela que vai mostrar as fun\u00e7\u00f5es e vantagens da sua API.<\/p>\n<p dir=\"ltr\">Independentemente da fun\u00e7\u00e3o ou objetivo da API, existem alguns crit\u00e9rios b\u00e1sicos que toda API deve ter em sua documenta\u00e7\u00e3o.<\/p>\n<h2 dir=\"ltr\" id=\"indice-1\" data-indice=\"1\" data-viewport=\"indice\">6 boas pr\u00e1ticas para documentar uma API<\/h2>\n<p dir=\"ltr\">Deixar de elaborar qualquer um desses recursos pode ter efeitos drasticamente negativos na ado\u00e7\u00e3o, compreens\u00e3o e usabilidade. Para que isso n\u00e3o aconte\u00e7a, trouxemos <strong>6 boas pr\u00e1ticas<\/strong> a respeito do assunto, confira!<\/p>\n<h3 dir=\"ltr\">1. Elabore uma documenta\u00e7\u00e3o completa<\/h3>\n<p dir=\"ltr\">\u00c9 preciso lembrar que a documenta\u00e7\u00e3o deve conter todo conte\u00fado que auxilie os usu\u00e1rios e desenvolvedores a interagir com a sua API. Por causa disso, \u00e9 importante detalhar todos os dados.<\/p>\n<p dir=\"ltr\"><strong>Observa\u00e7\u00e3o:<\/strong> cada API pode ter particularidades diferentes, por isso, avalie o caso em espec\u00edfico.<\/p>\n<p dir=\"ltr\">Parta da premissa de que quanto menos tempo de pesquisa externa por parte do desenvolvedor, melhor. Neste sentido, <strong>boas dicas<\/strong> seria:<\/p>\n<ul>\n<li dir=\"ltr\">Enumerar os <em>endpoints<\/em> e par\u00e2metros;<\/li>\n<li dir=\"ltr\">Informar todas as funcionalidades detalhadamente;<\/li>\n<li dir=\"ltr\">Elaborar tutoriais e termos de uso, quando necess\u00e1rio.<\/li>\n<\/ul>\n<p><strong>aten\u00e7\u00e3o!<\/strong><\/p>\n<p>Outro fator importante \u00e9 detalhar as \u00faltimas atualiza\u00e7\u00f5es e as implica\u00e7\u00f5es no uso, pois isso ajuda a entender a estabilidade da API no momento da integra\u00e7\u00e3o.<\/p>\n<h3 dir=\"ltr\">2. Disponibilize muitos exemplos<\/h3>\n<p dir=\"ltr\">\u00c9 muito interessante que voc\u00ea utilize diversos&nbsp; exemplos de c\u00f3digo para que o desenvolvedor fa\u00e7a a liga\u00e7\u00e3o entre o conceito que voc\u00ea est\u00e1 passando e sua aplica\u00e7\u00e3o pr\u00e1tica na API de forma r\u00e1pida.<\/p>\n<p dir=\"ltr\">O ideal \u00e9 que a sua documenta\u00e7\u00e3o seja desenvolvida da forma mais acess\u00edvel e no maior n\u00famero de linguagens poss\u00edvel para o maior n\u00famero de desenvolvedores, al\u00e9m do mais, n\u00e3o \u00e9 poss\u00edvel conhecer todo o p\u00fablico que utilizar\u00e1 a documenta\u00e7\u00e3o.<\/p>\n<h3 dir=\"ltr\">3. Centralize informa\u00e7\u00f5es<\/h3>\n<p dir=\"ltr\">Outro ponto que merece destaque \u00e9 centraliza\u00e7\u00e3o das informa\u00e7\u00f5es, ou seja, evite redund\u00e2ncias, v\u00e1 direto ao ponto.&nbsp;<\/p>\n<p dir=\"ltr\">Evite dividir a documenta\u00e7\u00e3o em v\u00e1rias p\u00e1ginas sobre o mesmo assunto, fa\u00e7a de forma que seja completa e concisa.<\/p>\n<p dir=\"ltr\">Uma boa pr\u00e1tica nesse tema \u00e9 tentar manter os t\u00f3picos que possuam rela\u00e7\u00e3o mais pr\u00f3ximos uns aos outros em uma mesma p\u00e1gina, isso reduz o tempo de procura a respeito de um determinado assunto.<\/p>\n<h3 dir=\"ltr\">4. Fique atento \u00e0s mensagens de erro<\/h3>\n<p dir=\"ltr\">Erros durante e a ap\u00f3s a documenta\u00e7\u00e3o poder\u00e3o acontecer, e isso far\u00e1 com que voc\u00ea perca muito tempo tentando resolv\u00ea-los.<\/p>\n<p dir=\"ltr\">Portanto, para facilitar, uma boa dica \u00e9 substituir as mensagens de erro gen\u00e9ricas por mensagens explicativas ou referenciadas por c\u00f3digos que tenham explica\u00e7\u00e3o na sua documenta\u00e7\u00e3o.<\/p>\n<p dir=\"ltr\">\u200b<\/p>\n<h3 dir=\"ltr\">5. Invista em interatividade<\/h3>\n<p dir=\"ltr\">Viabilizar que os usu\u00e1rios possam interagir com a API a partir da sua documenta\u00e7\u00e3o e vice-versa far\u00e1 com que o desenvolvedor passe a entender mais r\u00e1pido a documenta\u00e7\u00e3o e comece de pronto a utilizar as ferramentas.<\/p>\n<p dir=\"ltr\">Esse tipo de experi\u00eancia \u00e9 mais positiva pois traz maior din\u00e2mica e deixa as integra\u00e7\u00f5es mais r\u00e1pidas e com melhor qualidade.<\/p>\n<h3 dir=\"ltr\">6. Teste sua documenta\u00e7\u00e3o<\/h3>\n<p dir=\"ltr\">O \u00f3bvio precisa ser dito: sua documenta\u00e7\u00e3o precisa ser coerente e possuir dados concretos.<\/p>\n<p dir=\"ltr\">Portanto, crie uma fase de testes. Avalie tudo que foi colocado sobre sua API e, se poss\u00edvel, conte com uma equipe de desenvolvedores que n\u00e3o participou do desenvolvimento dela, pois eles ter\u00e3o um olhar diferente de quem j\u00e1 estava trabalhando no projeto.<\/p>\n<h2 dir=\"ltr\" id=\"indice-2\" data-indice=\"2\" data-viewport=\"indice\">Quais os principais problemas ao documentar uma API?<\/h2>\n<p dir=\"ltr\">Este de fato \u00e9 um cen\u00e1rio abrangente, mas reunimos algumas dicas abordando os <strong>principais t\u00f3picos<\/strong> que costumam gerar d\u00favidas no momento de documentar uma API. Veja:<\/p>\n<h3 dir=\"ltr\">Estrutura abrangente<\/h3>\n<p dir=\"ltr\">A estrutura abrangente da documenta\u00e7\u00e3o pode ser a parte mais dif\u00edcil de corrigir. Por isso, procure uma estrutura clara e intuitiva.<\/p>\n<p dir=\"ltr\">Isso proporcionar\u00e1 um grande al\u00edvio n\u00e3o apenas aos desenvolvedores iniciantes, mas tamb\u00e9m aos colaboradores internos que esperam manter a consist\u00eancia \u00e0 medida que adicionam novas informa\u00e7\u00f5es \u00e0 documenta\u00e7\u00e3o.&nbsp;<\/p>\n<p dir=\"ltr\">Para vencer essa barreira, siga as <strong>3 dicas<\/strong> que trouxemos abaixo:<\/p>\n<h4 dir=\"ltr\">1. Invista em uma introdu\u00e7\u00e3o s\u00f3lida<\/h4>\n<p dir=\"ltr\">Voc\u00ea provavelmente gastou centenas, sen\u00e3o milhares de horas desenvolvendo seu produto e suas plataformas. Mas lembre-se de que seus usu\u00e1rios n\u00e3o. Mesmo quest\u00f5es que parecem b\u00e1sicas para voc\u00ea podem n\u00e3o ser t\u00e3o intuitivas para um novo cliente.<\/p>\n<p dir=\"ltr\">Portanto, use a introdu\u00e7\u00e3o para familiarizar um novo usu\u00e1rio com os conceitos b\u00e1sicos de seu servi\u00e7o e sua plataforma, seja um sistema operacional como o Android ou uma linguagem como Java ou Swift.<\/p>\n<p dir=\"ltr\">A documenta\u00e7\u00e3o do <a href=\"https:\/\/docs.sendbird.com\/platform\/quick_start\" style=\"outline: none;\" target=\"_blank\" rel=\"noopener\">Sendbird<\/a> fornece um exemplo. A API da plataforma fornece uma se\u00e7\u00e3o de in\u00edcio r\u00e1pido, onde s\u00e3o introduzidos alguns conceitos b\u00e1sicos que auxilia alguns programadores menos experientes, veja:<\/p>\n<p><span><img decoding=\"async\" alt=\"Quick Start _ Platform API Chat SDK Documentation _ Sendbird\" data-id=\"10613\" width=\"702\" data-init-width=\"702\" height=\"382\" data-init-height=\"382\" title=\"Quick Start _ Platform API Chat SDK Documentation _ Sendbird\" loading=\"lazy\" src=\"https:\/\/enotas.com.br\/blog\/wp-content\/uploads\/2020\/07\/Quick-Start-_-Platform-API-Chat-SDK-Documentation-_-Sendbird-Google-Chrome-2020-06-23-19-03-59_Trim_Trim.gif\" data-width=\"702\" data-height=\"382\"><\/span><\/p>\n<p dir=\"ltr\">E neste momento voc\u00ea pode se perguntar: &#8220;Quem n\u00e3o sabe sobre seguran\u00e7a de URL?&#8221; Mas garanto que ficaria surpreso com quantos relat\u00f3rios de erros poderiam ser cortados pela raiz com adi\u00e7\u00f5es t\u00e3o simples!<\/p>\n<p dir=\"ltr\">Claro, sempre existe o perigo de explicar coisas que realmente n\u00e3o precisam de explica\u00e7\u00e3o. Mas \u00e9 melhor prevenir do que remediar, n\u00e3o?&nbsp;<\/p>\n<p dir=\"ltr\">Entretanto, procure mais por instru\u00e7\u00f5es do que redund\u00e2ncia, seja direto e claro. Explica\u00e7\u00f5es desnecess\u00e1rias devem ser evitadas tanto quanto excluir conceitos b\u00e1sicos.&nbsp;<\/p>\n<p dir=\"ltr\">Se ajudar, imagine que voc\u00ea \u00e9 um instrutor em uma sala de aula ensinando os alunos nessa disciplina. O que ajudaria o aluno a desenvolver esse processo?<\/p>\n<h4 dir=\"ltr\">2. Deixe seu leitor experimentar o recurso principal o mais r\u00e1pido poss\u00edvel<\/h4>\n<p dir=\"ltr\">Ao disponibilizar \u00e1reas de testes, voc\u00ea entrega confian\u00e7a e permite que o usu\u00e1rio tenha uma breve experi\u00eancia com a ferramenta, o que gera um ponto positivo \u00e0 sua documenta\u00e7\u00e3o.<\/p>\n<p dir=\"ltr\">O Firebase Database, por exemplo, disponibiliza um banco de dados em tempo real. Caso tenha interesse, basta voc\u00ea acessar o <a href=\"https:\/\/firebase.google.com\/docs\/guides?hl=pt-br\" style=\"outline: none;\" target=\"_blank\" rel=\"noopener\">guia de instru\u00e7\u00f5e<\/a>s na p\u00e1gina oficial do aplicativo.<\/p>\n<p><span><img decoding=\"async\" alt=\"Guia Firebase\" data-id=\"10605\" width=\"760\" data-init-width=\"933\" height=\"631\" data-init-height=\"775\" title=\"Guia Firebase\" loading=\"lazy\" src=\"https:\/\/enotas.com.br\/blog\/wp-content\/uploads\/2020\/07\/Guia-Firebase.png\" data-width=\"760\" data-height=\"631\"><\/span><\/p>\n<p dir=\"ltr\">Por l\u00e1, voc\u00ea conseguir\u00e1 diversos <strong>passo a passos<\/strong> para executar as principais atividades, inclusive consultar a biblioteca dispon\u00edvel, veja:<\/p>\n<p dir=\"ltr\"><img decoding=\"async\" src=\"https:\/\/lh3.googleusercontent.com\/Og70LmrGGFW90TJdroknGDtGRqhx7ujMCmIHYYl4PxAsyzsOJraZ6odBrSxFk9MB3YdNpDLiYRDjgT_TUCHTOXJnKNIpEw6ctPkbJJL37cYXYoKGWyJcRShGhTjDaICE2CeVyvmK\" width=\"602\" height=\"263\"><\/p>\n<p dir=\"ltr\"><strong>Dica:<\/strong> Voc\u00ea n\u00e3o deseja que os usu\u00e1rios aprendam sobre o envio de arquivos criptografados antes de aprenderem sobre a configura\u00e7\u00e3o da API. Ent\u00e3o, d\u00ea a eles um ponto de partida para que eles possam tentar os recursos avan\u00e7ados por conta pr\u00f3pria.<\/p>\n<p dir=\"ltr\">Dentro desse cen\u00e1rio, o Stripe fornece um exemplo brilhante, veja s\u00f3:<\/p>\n<p dir=\"ltr\">&#8211; V\u00e1 para a p\u00e1gina de documentos: <a href=\"https:\/\/stripe.com\/docs\" style=\"outline: none;\" target=\"_blank\" rel=\"noopener\">https:\/\/stripe.com\/docs<\/a> e crie uma conta.<\/p>\n<p dir=\"ltr\">&#8211; Voc\u00ea ver\u00e1 imediatamente uma se\u00e7\u00e3o interativa &#8220;Experimente agora&#8221;, que permite testar a API de pagamento em alguns minutos.<\/p>\n<p><span><img decoding=\"async\" alt=\"stripe\" data-id=\"10606\" width=\"760\" data-init-width=\"1312\" height=\"566\" data-init-height=\"977\" title=\"stripe\" loading=\"lazy\" src=\"https:\/\/enotas.com.br\/blog\/wp-content\/uploads\/2020\/07\/stripe.png\" data-width=\"760\" data-height=\"566\"><\/span><\/p>\n<p dir=\"ltr\">\n<p dir=\"ltr\"><strong>Observa\u00e7\u00e3o: <\/strong>Neste caso, a documenta\u00e7\u00e3o ignora os detalhes sobre a configura\u00e7\u00e3o da API com cart\u00f5es de cr\u00e9dito, usu\u00e1rios, cobran\u00e7as e assinaturas.<\/p>\n<p dir=\"ltr\">A\u00e7\u00f5es como essa s\u00e3o interessantes pois permitem, por exemplo, que um desenvolvedor experimente uma implementa\u00e7\u00e3o funcional.<\/p>\n<h4 dir=\"ltr\">3. Evite categoriza\u00e7\u00f5es excessivas<\/h4>\n<p dir=\"ltr\">Pode ser tentador subcategorizar tudo em grupos l\u00f3gicos. Entretanto, evite o aninhamento excessivo.<\/p>\n<p dir=\"ltr\">Veja s\u00f3 o seguinte exemplo:<\/p>\n<p dir=\"ltr\"><em><span style=\"font-size: 16px;\">1. Mensagens<\/span><\/em><\/p>\n<p dir=\"ltr\"><span style=\"font-size: 16px;\"><em>&nbsp;&nbsp;&nbsp;&nbsp;1.1 Enviando mensagens<\/em><\/span><\/p>\n<p dir=\"ltr\"><span style=\"font-size: 16px;\"><em>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;a. Enviando mensagens de texto<\/em><\/span><\/p>\n<p dir=\"ltr\"><span style=\"font-size: 16px;\"><em>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;b. Enviando arquivos<\/em><\/span><\/p>\n<p dir=\"ltr\"><span style=\"font-size: 16px;\"><em>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;i. Enviando arquivos bin\u00e1rios<\/em><\/span><\/p>\n<p dir=\"ltr\"><span style=\"font-size: 16px;\"><em>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;* Multipart requests<\/em><\/span><\/p>\n<p dir=\"ltr\"><em><span style=\"font-size: 16px;\">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; * Usando multipart requests para enviar arquivos bin\u00e1rios<\/span><\/em><\/p>\n<p dir=\"ltr\">O primeiro problema de escritas como essa \u00e9 que elas tornam as se\u00e7\u00f5es dif\u00edceis de se localizar.&nbsp;<\/p>\n<p dir=\"ltr\">Um menu de navega\u00e7\u00e3o lateral, por exemplo, &nbsp;n\u00e3o seria capaz de exibir se\u00e7\u00f5es aninhadas com <strong>mais de 2 n\u00edveis<\/strong>, apesar de em alguns casos ser interessante estender um \u00fanico n\u00edvel.<\/p>\n<p dir=\"ltr\">O segundo problema est\u00e1 relacionado ao bom design. Como voc\u00ea distinguiria todos os cabe\u00e7alhos &#8211; h1 a h6 &#8211; para que os usu\u00e1rios pudessem saber intuitivamente onde eles est\u00e3o na documenta\u00e7\u00e3o?<\/p>\n<p dir=\"ltr\">Portanto, uma solu\u00e7\u00e3o seria fazer da seguinte forma:<\/p>\n<p dir=\"ltr\"><em><span style=\"font-size: 16px;\">1. mensagens<\/span><\/em><\/p>\n<p dir=\"ltr\"><span style=\"font-size: 16px;\"><em>&nbsp;&nbsp;&nbsp;&nbsp;1.1 Enviando mensagens de texto<\/em><\/span><\/p>\n<p dir=\"ltr\"><span style=\"font-size: 16px;\"><em>&nbsp;&nbsp;&nbsp;&nbsp;1.2 Enviando arquivos<\/em><\/span><\/p>\n<p dir=\"ltr\"><span style=\"font-size: 16px;\"><em>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;a. Enviando arquivos bin\u00e1rios<\/em><\/span><\/p>\n<p dir=\"ltr\"><em><span style=\"font-size: 16px;\">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; (+ defina os multipart requests com um par\u00e1grafo sem t\u00edtulo)<\/span><\/em><\/p>\n<p dir=\"ltr\">Desta forma, ao nivelar a estrutura do seu documento, voc\u00ea encontra um equil\u00edbrio entre categoriza\u00e7\u00e3o e localiza\u00e7\u00e3o.&nbsp;<\/p>\n<p dir=\"ltr\">Seria l\u00f3gico agrupar &#8220;enviar mensagens de texto&#8221; e &#8220;enviar mensagens de arquivo&#8221;, mas a simplicidade sai muito mais em conta para um desenvolvedor que procura encontrar uma solu\u00e7\u00e3o para um problema no <strong>menor tempo poss\u00edvel.<\/strong><\/p>\n<h3 dir=\"ltr\">Formata\u00e7\u00e3o<\/h3>\n<p dir=\"ltr\">A documenta\u00e7\u00e3o moderna traz grande import\u00e2ncia ao design e formata\u00e7\u00e3o. Neste sentido, tome como exemplo os documentos da <a href=\"https:\/\/developers.google.com\/gmail\/api\" style=\"outline: none;\" target=\"_blank\" rel=\"noopener\">API do Gmail<\/a>:<\/p>\n<ul>\n<li dir=\"ltr\">As caixas coloridas incluem notas importantes.<\/li>\n<li dir=\"ltr\">A documenta\u00e7\u00e3o destaca os principais caminhos nos terminais.<\/li>\n<li dir=\"ltr\">As tabelas apresentam informa\u00e7\u00f5es de maneira concisa e leg\u00edvel.<\/li>\n<li dir=\"ltr\">A refer\u00eancia da API do Stripe \u00e9 bem projetada.&nbsp;<\/li>\n<li dir=\"ltr\">O layout de duas colunas maximiza o espa\u00e7o na tela.<\/li>\n<\/ul>\n<p dir=\"ltr\">Sendo assim, ao planejar seus pr\u00f3prios documentos, imagine como os itens devem ser exibidos. Lembre-se de que os elementos projetados devem ser reutiliz\u00e1veis e consistentes em diversos contextos.<\/p>\n<p dir=\"ltr\">Dentro desse contexto, confira <strong>3 boas pr\u00e1ticas<\/strong> que te ajudar\u00e3o nesse processo:<\/p>\n<h4 dir=\"ltr\">1. Lightweight Markup Language (LML) \u00e9 uma boa op\u00e7\u00e3o<\/h4>\n<p dir=\"ltr\">Como a documenta\u00e7\u00e3o, geralmente, \u00e9 renderizada em um site, ela \u00e9 baseada em HTML. No entanto, o uso de HTML bruto para escrever documenta\u00e7\u00e3o \u00e9 demorado e propenso a erros.<\/p>\n<p dir=\"ltr\">Um LML como o <a href=\"https:\/\/daringfireball.net\/projects\/markdown\/syntax\" style=\"outline: none;\" target=\"_blank\" rel=\"noopener\">Markdown<\/a>, por exemplo, torna a escrita para a Web mais r\u00e1pida e eficiente.<\/p>\n<p dir=\"ltr\">Digamos que voc\u00ea tenha um cabe\u00e7alho, um par\u00e1grafo e um link dentro do par\u00e1grafo. Em HTML voc\u00ea teria algo parecido com isto:<\/p>\n<p dir=\"ltr\"><em><span style=\"font-size: 16px;\">&lt;h1&gt; Cabe\u00e7alho aqui &lt;\/h1&gt;<\/span><\/em><\/p>\n<p dir=\"ltr\"><em><span style=\"font-size: 16px;\">&lt;p&gt; Consulte este &lt;a href=&#8221;https:\/\/www.example.com\/&#8221;&gt; link &lt;\/a&gt; para obter uma descri\u00e7\u00e3o mais detalhada. &lt;\/p&gt;<\/span><\/em><\/p>\n<p dir=\"ltr\">Compare isso com o mesmo conte\u00fado escrito em Markdown:<\/p>\n<p dir=\"ltr\"><em><span style=\"font-size: 16px;\">#Cabe\u00e7alho aqui&nbsp;<\/span><\/em><\/p>\n<p dir=\"ltr\"><em><span style=\"font-size: 16px;\">Consulte este [link] (https:\/\/www.example.com\/) para obter uma descri\u00e7\u00e3o mais detalhada.<\/span><\/em><\/p>\n<h4 dir=\"ltr\">2. Fa\u00e7a tudo em uma p\u00e1gina (a menos que voc\u00ea tenha uma boa raz\u00e3o para extrapolar)<\/h4>\n<p dir=\"ltr\">O porqu\u00ea disso \u00e9 muito claro. Ningu\u00e9m deseja clicar em tr\u00eas links aninhados para encontrar a resposta para uma pergunta simples.&nbsp;<\/p>\n<p dir=\"ltr\">Desde que voc\u00ea tenha uma barra lateral listando todas as se\u00e7\u00f5es, uma \u00fanica p\u00e1gina de documenta\u00e7\u00e3o permite obter uma vis\u00e3o panor\u00e2mica.<\/p>\n<p dir=\"ltr\">Um exemplo disso \u00e9 a plataforma do <a href=\"http:\/\/docs.parseplatform.org\/android\/guide\/\" style=\"outline: none;\" target=\"_blank\" rel=\"noopener\">Parse Android<\/a>.<\/p>\n<p><span><img decoding=\"async\" alt=\"parse android\" data-id=\"10607\" width=\"760\" data-init-width=\"1564\" height=\"436\" data-init-height=\"897\" title=\"parse android\" loading=\"lazy\" src=\"https:\/\/enotas.com.br\/blog\/wp-content\/uploads\/2020\/07\/parse-android.png\" data-width=\"760\" data-height=\"436\"><\/span><\/p>\n<p dir=\"ltr\">\n<p dir=\"ltr\">Voc\u00ea pode ver que o Parse cont\u00e9m componentes como \u201cUsu\u00e1rios\u201d, \u201cObjetos\u201d e \u201cSess\u00f5es\u201d f\u00e1ceis de encontrar e sem a necessidade de consultar um &#8220;\u00edndice&#8221; separado, ou ter de usar o \u201cctrl+F\u201d.<\/p>\n<p dir=\"ltr\">Mas digamos que voc\u00ea tenha uma API extensa. A compacta\u00e7\u00e3o de todas essas informa\u00e7\u00f5es em uma \u00fanica p\u00e1gina seria inconveniente e levaria a um carregamento lento da p\u00e1gina.&nbsp;<\/p>\n<p dir=\"ltr\">Neste caso, um \u00f3timo exemplo a seguir s\u00e3o os documentos de API do <a href=\"https:\/\/developer.github.com\/v3\/\" style=\"outline: none;\" target=\"_blank\" rel=\"noopener\">GitHub<\/a>. Eles mant\u00eam uma barra lateral persistente, mas carregam cada documento em uma \u00fanica p\u00e1gina.<\/p>\n<p><span><img decoding=\"async\" alt=\"Activity _ GitHub Developer Guide\" data-id=\"10612\" width=\"702\" data-init-width=\"702\" height=\"382\" data-init-height=\"382\" title=\"Activity _ GitHub Developer Guide\" loading=\"lazy\" src=\"https:\/\/enotas.com.br\/blog\/wp-content\/uploads\/2020\/07\/Activity-_-GitHub-Developer-Guide-Google-Chrome-2020-06-23-19-29-56_Trim.gif\" data-width=\"702\" data-height=\"382\"><\/span><\/p>\n<h4 dir=\"ltr\">3. Use tabelas<\/h4>\n<p dir=\"ltr\">A documenta\u00e7\u00e3o do c\u00f3digo cont\u00e9m muitas informa\u00e7\u00f5es. O uso de tabelas transmite esses dados de forma sucinta, especialmente para par\u00e2metros e vari\u00e1veis de c\u00f3digo.<\/p>\n<p dir=\"ltr\">Neste caso, o recomendado \u00e9 usar uma estrutura de 4 colunas para documentar solicita\u00e7\u00f5es e respostas teste.<\/p>\n<table data-rows=\"2\" data-cols=\"4\">\n<thead><\/thead>\n<tbody>\n<tr>\n<td data-th=\"Nome\">Nome<\/td>\n<td data-th=\"Tipo\">Tipo<\/td>\n<td data-th=\"Descri\u00e7\u00e3o\">Descri\u00e7\u00e3o<\/td>\n<td data-th=\"Marca\u00e7\u00e3o1\">Marca\u00e7\u00e3o1<\/td>\n<\/tr>\n<tr>\n<td data-th=\"Nome\">Timestamp<\/td>\n<td data-th=\"Tipo\">Long<\/td>\n<td data-th=\"Descri\u00e7\u00e3o\">\n<p style=\"text-align: left;\">O hor\u00e1rio em que o usu\u00e1rio recebeu sua primeira mensagem<\/p>\n<\/td>\n<td data-th=\"Marca\u00e7\u00e3o1\">Em milissegundos<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<table>\n<tbody>\n<tr>\n<td>\n<p dir=\"ltr\">\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p dir=\"ltr\">O <a href=\"https:\/\/docs.sendbird.com\/platform?utm_source=Blog&amp;utm_medium=Referral-Text#user_3_create_a_user\" style=\"outline: none;\" target=\"_blank\" rel=\"noopener\">Sendbird<\/a> segue uma estrutura semelhante, mas usa 3 colunas, optando por mesclar &#8220;descri\u00e7\u00e3o&#8221; e &#8220;marca\u00e7\u00e3o&#8221;.&nbsp;<\/p>\n<p dir=\"ltr\">Vale lembrar que tabelas com muitas colunas n\u00e3o costumam ser bem exibidas em sites. Portanto, voc\u00ea deve encontrar um equil\u00edbrio entre adicionar colunas e escrever coisas em uma coluna geral de &#8220;descri\u00e7\u00e3o&#8221;.<\/p>\n<p dir=\"ltr\">Para isso, voc\u00ea deve escolher entre uma uma coluna de &#8220;par\u00e2metro obrigat\u00f3rio&#8221;,&nbsp; Uma coluna de &#8220;valor padr\u00e3o&#8221;, ou apenas adicionar uma de &#8220;descri\u00e7\u00f5es&#8221;.&nbsp; A melhor op\u00e7\u00e3o ir\u00e1 depender do design da sua API.<\/p>\n<h3 dir=\"ltr\">Escrita e gram\u00e1tica<\/h3>\n<p dir=\"ltr\">Voc\u00ea pode achar que a gram\u00e1tica envolvida na reda\u00e7\u00e3o t\u00e9cnica \u00e9 um pouco entediante e, bem, excessivamente t\u00e9cnica. Bom, para isso trouxemos <strong>mais 3 boas pr\u00e1ticas<\/strong> para te auxiliar nesse processo:<\/p>\n<h4 dir=\"ltr\">1. Dirija-se ao leitor usando &#8220;voc\u00ea&#8221; e use a voz ativa<\/h4>\n<p dir=\"ltr\">Agora \u00e9 convencional abordar o leitor com &#8220;voc\u00ea&#8221;. Olhe para o gigante da internet local, o Google. &#8220;Voc\u00ea&#8221; \u00e9 abundante em sua documenta\u00e7\u00e3o e tamb\u00e9m o incentiva a escrever na voz ativa.<\/p>\n<p dir=\"ltr\">Como sua documenta\u00e7\u00e3o \u00e9 um manual de instru\u00e7\u00f5es para um desenvolvedor individual fazer algo, sua escrita deve enfatizar <strong>o agente e suas a\u00e7\u00f5es<\/strong>.&nbsp;<\/p>\n<p dir=\"ltr\">Portanto n\u00e3o use algo como: &#8220;O c\u00f3digo \u00e9 escrito por um desenvolvedor&#8221;.<\/p>\n<p dir=\"ltr\">Em vez disso, escreva: &#8220;Um desenvolvedor escreve o c\u00f3digo&#8221;.<\/p>\n<h4 dir=\"ltr\">2. Use o pronome &#8220;eles&#8221; para ser mais abrangente<\/h4>\n<p dir=\"ltr\">\u00c9 complicado escrever sempre \u201cele ou ela\u201d. No entanto, \u00e9 importante incluir homens, mulheres e outros g\u00eaneros entre seus leitores.<\/p>\n<p dir=\"ltr\">Por ser tecnicamente incorreto usar o pronome plural para se referir a um substantivo singular, vamos tentar levar o substantivo sempre para o plural.<\/p>\n<p dir=\"ltr\">Portanto, use &#8220;Eles&#8221; em vez de &#8220;ele ou ela&#8221;. Vamos usar um exemplo. Muitos documentos da API falam sobre &#8220;usu\u00e1rios&#8221;.<\/p>\n<p dir=\"ltr\">N\u00c3O fa\u00e7a o seguinte:<\/p>\n<p dir=\"ltr\"><em>&#8220;Um usu\u00e1rio pode encontrar o X. Nesse caso, voc\u00ea pode fornecer a ele o recurso Y.&#8221;<\/em><\/p>\n<p dir=\"ltr\">Neste caso, basta usar &#8220;eles&#8221;. Ficaria assim:<\/p>\n<p dir=\"ltr\"><em>&#8220;Os usu\u00e1rios podem encontrar o X. Nesse caso, voc\u00ea pode fornecer a eles o recurso Y.&#8221;<\/em><\/p>\n<h4 dir=\"ltr\">3. Mantenha a escrita do t\u00edtulo consistente.<\/h4>\n<p dir=\"ltr\">Existem dois tipos principais de letras mai\u00fasculas usadas nos t\u00edtulos:<\/p>\n<ul>\n<li dir=\"ltr\">&nbsp;&#8220;Cozinhar uma \u00d3tima Torta de Ma\u00e7\u00e3&#8221;;<\/li>\n<li dir=\"ltr\">&nbsp;&#8220;Cozinhar uma \u00f3tima torta de ma\u00e7\u00e3&#8221;.<\/li>\n<\/ul>\n<p dir=\"ltr\">O primeiro coloca em mai\u00fascula as principais palavras de acordo com um padr\u00e3o. J\u00e1 o segundo caso \u00e9 chamado de <strong>senten\u00e7a de exemplo<\/strong>.<\/p>\n<p dir=\"ltr\">Para t\u00edtulos longos, a caixa de senten\u00e7as tende a ser mais leg\u00edvel, mas esse \u00e9 um crit\u00e9rio que depende exclusivamente de voc\u00ea. Apenas certifique-se de que voc\u00ea e seus futuros colaboradores sejam consistentes, beleza?<\/p>\n<p dir=\"ltr\"><strong>Conclus\u00e3o<\/strong><\/p>\n<p dir=\"ltr\">Como voc\u00ea p\u00f4de perceber, existem v\u00e1rios aspectos que precisam de aten\u00e7\u00e3o na fase de documenta\u00e7\u00e3o de uma API, al\u00e9m do mais, o objetivo \u00e9 que seus parceiros e clientes tenham uma boa experi\u00eancia e integrem seus servi\u00e7os com efici\u00eancia.<\/p>\n<p dir=\"ltr\">A API pode ser a interface entre um aplicativo e o c\u00f3digo de back-end, mas a documenta\u00e7\u00e3o conecta voc\u00ea a seus usu\u00e1rios.&nbsp;<\/p>\n<p dir=\"ltr\">Escrever uma boa documenta\u00e7\u00e3o n\u00e3o \u00e9 uma tarefa f\u00e1cil e provavelmente ser\u00e1 um processo iterativo de feedback e revis\u00e3o.<\/p>\n<p dir=\"ltr\">Agora que voc\u00ea j\u00e1 teve acesso a nossas dicas e sabe como documentar uma API, que tal aproveitar e descobrir sobre o <a href=\"https:\/\/enotas.com.br\/blog\/postman\/\" style=\"outline: none;\" target=\"_blank\" rel=\"noopener\">Postman<\/a>, uma ferramenta que pode te ajudar bastante com a documenta\u00e7\u00e3o das solicita\u00e7\u00f5es feitas pela API!<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Acompanhe o nosso guia e descubra a import\u00e2ncia de documentar uma API e tenha acesso a boas pr\u00e1ticas para realizar essa atividade de forma eficiente! API&#8217;s vem da abrevia\u00e7\u00e3o do termo &#8220;Application Programming Interface&#8221; e, como o pr\u00f3prio nome diz, com elas, \u00e9 poss\u00edvel criar interfaces para que sejam feitas integra\u00e7\u00f5es entre um ou mais [&#8230;]<\/p>\n","protected":false},"author":15,"featured_media":10599,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7,205],"tags":[],"class_list":["post-10597","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-legalizacao","category-tech"],"_links":{"self":[{"href":"https:\/\/enotas.com.br\/blog\/wp-json\/wp\/v2\/posts\/10597","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/enotas.com.br\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/enotas.com.br\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/enotas.com.br\/blog\/wp-json\/wp\/v2\/users\/15"}],"replies":[{"embeddable":true,"href":"https:\/\/enotas.com.br\/blog\/wp-json\/wp\/v2\/comments?post=10597"}],"version-history":[{"count":12,"href":"https:\/\/enotas.com.br\/blog\/wp-json\/wp\/v2\/posts\/10597\/revisions"}],"predecessor-version":[{"id":27690,"href":"https:\/\/enotas.com.br\/blog\/wp-json\/wp\/v2\/posts\/10597\/revisions\/27690"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/enotas.com.br\/blog\/wp-json\/wp\/v2\/media\/10599"}],"wp:attachment":[{"href":"https:\/\/enotas.com.br\/blog\/wp-json\/wp\/v2\/media?parent=10597"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/enotas.com.br\/blog\/wp-json\/wp\/v2\/categories?post=10597"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/enotas.com.br\/blog\/wp-json\/wp\/v2\/tags?post=10597"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}