A integridade da documentação de um API determina a sua utilidade. Utilizar procedimentos padrão ao escrever documentação de APIs REST para criar um manual que seja mais simples de ler e compreender para todos os leitores. A documentação das APIs REST torna possível um guia de referência rápido que cobre tudo o que se necessita para aprender sobre a API, incluindo informação sobre procedimentos, categorias, tipos de resultados, parâmetros, e mais. Este artigo irá guiá-lo sobre as APIs REST, como escrever documentos API REST e dicas e ferramentas para escrever documentação.
Sobre as APIs de REST
As API REST facilitam a comunicação entre várias aplicações da Internet. É possível obter dados de outro programa quando se utiliza um. Pode utilizar o RESTful API em vez dos métodos convencionais, que levam mais tempo e são menos seguros. Utilizando uma API, é possível obter dados de um sistema sem se envolver com a interface do utilizador.
REST é uma abordagem popular de desenho arquitectónico e programação para plataformas hipermedia em rede e outras tecnologias web. Por exemplo, o Instagram API devolverá o estado do utilizador, identidade, ligações, e tweets partilhados quando um programador pede para obter o objecto de um cliente. Graças à integração da API, isto é viável.
Como é que se escreve a documentação API?
Uma melhor documentação deve servir como guia e ferramenta educacional, permitindo aos programadores encontrar rapidamente os detalhes de que necessitam num relance e aprender como incorporar a técnica que estão a considerar, revendo a documentação. Como resultado, a documentação adequada deve ser simultaneamente concisa e visível, oferecendo o seguinte:
- Uma descrição detalhada do que a técnica ou item faz
- Chamadas que transmitem detalhes cruciais aos criadores, tais como problemas e cautelas
- Um exemplo de chamada com o conteúdo do tipo de mídia correspondente
- Uma lista de verificação das variáveis utilizadas por esta técnica, juntamente com informações sobre os seus tipos, requisitos de estruturação particulares, e se forem necessários.
- Um exemplo de uma resposta com corpo do tipo de suporte
- Amostras de scripts em várias linguagens que contêm todo o código necessário (por exemplo, Java, .Net, Ruby, etc.)
- Exemplos SDK
- Demonstram como utilizar o SDK para que o seu dialecto chegue ao serviço ou procedimento.
- Actividades valiosas para testar e experimentar pedidos API (API Console, API Notebook)
- Consultas e situações com códigos são normalmente questionadas.
- Referências a websites relacionados (outros exemplos, blogs, etc.)
As melhores dicas para escrever a documentação RESTful API
Planeie a sua estratégia para escrever documentação
Ao iniciar o processo de documentação, deve elaborar uma estratégia minuciosa. A sua probabilidade de sucesso aumentará como resultado. Compreenda os leitores para os quais cria a documentação antes de documentar as APIs REST. Pode escolher facilmente a plataforma, estilo e layout certos para a sua documentação, se estiver ciente do público a que se destina.
Será mais fácil para si produzir material relevante que irá melhorar a utilização do seu API se tiver uma compreensão clara dos objectivos e do âmbito da documentação de APIs REST. Poderá organizar a documentação para melhor satisfazer os requisitos do utilizador, escrevendo APIs REST com eles em consideração.
Lembre-se de que os consumidores têm uma representação mental do seu cenário operacional quando utilizam as suas APIs. Por exemplo, os utilizadores considerarão provavelmente os custos de documentos API, devoluções, clientes, e cartões de débito se oferecerem um método de pagamento.
Por conseguinte, organizar os seus documentos dessa forma torna-o lógico. Considere estudar a documentação para a API da Stripe. Eles dão uma introdução decente antes de agrupar logicamente os APIs. GitHub oferece uma ilustração sólida da documentação RESTful API que é bem organizada, com secções para "GitHub information, problems, and members".
GitHub permite-lhe criar pedidos de extracção, filiais, e muito mais. Os documentos API do GitHub são de código aberto. A melhor parte sobre GitHub é que ele está sempre a esforçar-se para melhorar a experiência do programador de formas importantes.
Incluir secções básicas
A excelente documentação RESTful API deve incluir uma certa quantidade de peças. Tais porções centrais são essenciais para melhorar a clareza e aumentar a aceitação de APIs REST quando documentadas. Deve-se considerar alguns elementos essenciais ao documentar as APIs REST.
- Uma introdução à API de REST
- Como obter as credenciais dos utilizadores
- Recursos necessários para a utilização do API
- Mensagens de erro ao comunicar com o API
- Termos de utilização
Manter a integridade e afastar-se do jargão
A coerência no uso da terminologia em todo o texto é outro método útil para a documentação RESTful API. Utilizar um estilo de escrita consistente, livre de inconsistências linguísticas e de codificação. Remover quaisquer porções pouco claras ou desafiantes de compreender após uma revisão completa do seu conteúdo.
Utilizar sempre padrões consistentes de terminologia e vocabulário. Use a sua imaginação ao utilizar protocolos HTTP, códigos de estado, e outros nomes de itens comuns que possam levar a mal-entendidos. Por exemplo, ao descrever APIs REST, o verbo GET HTTP deve ser utilizado para consultar dados de um recurso especificado. Não terá de escrever muitas justificações se se ater a normas conhecidas, e o seu documento será mais simples de ler. Ajudaria se também se abstivesse de utilizar em demasia a linguagem técnica na descrição da sua API. Certifique-se de utilizar uma linguagem simples que fale de acordo com as exigências do seu público principal.
Adicione ilustrações interactivas
A maioria dos criadores gosta de testar o que leram na documentação para determinar se é eficaz. Numa linguagem de programação que a maioria dos programadores conhece, incluem-se programas de exemplo dinâmicos. Isto tornará o desenvolvimento de API menos complicado.
A inclusão de exemplos dinâmicos de API REST é uma técnica eficaz para baixar a curva de aprendizagem enquanto utiliza o seu API. Além disso, pode incluir informações de teste que os utilizadores podem utilizar para enviar sugestões e examinar os tipos de respostas que recebem.
Ao documentar as APIs REST, pode incluir outros materiais para além de exemplos ao vivo. Isto ajudará os utilizadores a tirar o máximo partido da API para além das informações oferecidas nas instruções. Um guia de configuração de contas, estruturas, ferramentas de desenvolvimento e seminários são alguns materiais que podem ser utilizados para aumentar a descrição do API.
Escrever para uma posição de nível de entrada
Os escritores profissionais, e não os criadores, geram frequentemente documentação. Isto acontece porque os escritores técnicos são especializados na interpretação de conceitos técnicos para uma linguagem compreensível. No entanto, muitos escritores técnicos utilizam vocabulário técnico nos seus manuais. Cada API é desenvolvido com um público específico em mente.
Os documentos API têm uma extensa audiência, incluindo desenvolvedores, equipas de julgamento e observadores. Os programadores comprometem-se com a documentação. A equipa de avaliação, tais como engenheiros e CTOs, compreendem rapidamente se o API é uma combinação adequada, e os espectadores, tais como escritores técnicos, repórteres, e os seus rivais.
Estes indivíduos têm deveres e talentos distintos e devem ser relaxados enquanto visualizam a documentação do seu API REST. Como resultado, deve concentrar-se nos consumidores mais inexperientes. Aplique as técnicas acima ao documentar as APIs REST para garantir que a documentação da API REST seja compreensível por pessoas com diferentes graus de conhecimento da API.
A melhor ferramenta para gerar a documentação RESTful API
O método pelo qual a documentação técnica foi racionalizada utilizando ferramentas para os APIs Restful. Os escritores técnicos podem utilizar estas ferramentas de documentação REST API para criar publicações técnicas, se estiverem familiarizados com a codificação. Uma vez que a utilização de criadores de documentação API é generalizada, os produtores mais famosos são gratuitos e apoiam o OpenAPI v3 está incluído abaixo. Os escritores técnicos utilizam estes recursos para produzir a documentação REST API.
SwaggerHub
SwaggerHub é uma plataforma de documentação API digital criada para racionalizar e agilizar a documentação da API Rest, tornando-a perfeita para equipas e empresas. Pode cumprir mais rapidamente as Especificações OpenAPI (OAS), anteriormente referidas como Swagger, empregando o editor da API.
Algumas das suas características são:
- Comunicação eficaz de erros e auto-completamento da linguagem
- Directrizes integradas de concepção de API que aplicam continuamente as normas
- Sítios Web para armazenar e utilizar a sintaxe da OEA que é universal através de API
- Acompanhamento de problemas e comentários em tempo real
- Proporciona uma excelente experiência de desenvolvimento
Redocly
O processo para a documentação REST API é automatizado usando Redocly's Workflows solutions. Pode manusear a sua documentação como código de programa utilizando documentos virtualizados, guardando-a em software de edição especial, estabelecendo um procedimento de auditoria, e entregando-a em várias configurações. Redocly As permissões de utilizador, verificação de tentativas, e outros mecanismos de autenticação do REST permitem-lhe garantir ainda mais que a sua equipa está a trabalhar em conjunto de forma eficaz e segura. A capacidade de visualização de Redocly é outra característica única. Para garantir que as suas modificações são avaliadas e debatidas antes de as enviar ao público, pode pré-visualizar cada projecto e pedidos de correcção.
Stoplight
Utilizando o utilitário de escrita REST API Stoplight, poderá construir e servir documentos API digitalmente. Utilizando este software, pode gerar documentação dinâmica REST API que pode distribuir interna e externamente para o público em geral. Pode incorporar artigos, manuais de instruções e amostras de código criados numa variedade de linguagens de programação, tais como JavaScript, Python, e Java.
Pode colocar a sua documentação no Stoplight, uma das características significativas da nossa solução de documentação REST API. Isto liberta-o de se preocupar com o funcionamento dos servidores e torna simples a utilização de conectores para lidar com as permissões e acompanhar as métricas.
ReadMe
Os seus documentos API podem tornar-se um centro dinâmico para os seus programadores com ReadMe. Podem criar exemplos de código automaticamente, alterar o material no editor ReadMe, integrar uma edição recomendada, responder a consultas no fórum de discussão, e mais neste centro.
Um dos benefícios mais significativos de ReadMe é que analisa análises como visitas a páginas, pedidos de API, falhas de API, e consultas a vários websites, entre outros, para que possa ver como a sua interface de programação de aplicações e documentação REST API é utilizada com o tempo. Utilizando estas métricas, a sua equipa pode determinar onde concentrar os seus esforços para melhorar.
apiDoc
Uma solução de documentação REST API de código aberto chamada apiDoc gera documentação a partir de uma base de código que contém detalhes de API. Com praticamente todas as linguagens de programação, é compatível. Os engenheiros podem observar o que foi modificado entre edições de uma API porque apiDoc permite que o faça. Isto facilita o tratamento limpo das actualizações de API, muitas vezes conhecidas como versionamento de API.
DapperDox
DapperDox foi desenvolvida por escritores de documentação da API RESTful para escritores de documentação da API REST, a fim de dar aos escritores a liberdade que desejam e aos programadores a legibilidade de que necessitam. Esta solução de documentos API da web é ideal para gerar uma colecção coerente de documentação que contém instruções inteligíveis e normas API da web, uma vez que permite aos escritores adicionar material pertinente a um site de descrição produzido. Além disso, pode cruzar referências conforme necessário, descrever vários requisitos API como um grupo de bens, e seleccionar temas para formatar os seus documentos de forma diferente.
DocGen por LucyBot
Pode gerar e gerir documentação API dinâmica utilizando LucyBot's DocGen. Este programa cria documentação para cada método e argumento API e responde instantaneamente. Pode criar uma Consola de API para permitir aos criadores e utilizadores executar pedidos de API experimental para examinar, resolver problemas e compreender a sua API potencialmente mais. Também pode criar processos que mostrem aos utilizadores exactamente que codificação devem criar e as etapas que devem seguir para completar um trabalho específico na linguagem de software que seleccionam.
AppMaster
Ao contrário de outras plataformas, AppMaster elimina a necessidade de um programador criar manualmente a documentação REST API e actualizá-la. A plataforma gera e actualiza automaticamente a documentação REST API no formato Swagger (OpenAPI) para cada aplicação e também inclui a Swagger UI em cada aplicação de servidor para facilitar a integração de desenvolvedores de terceiros com as aplicações geradas. Além disso, a plataforma AppMaster, ao gerar documentação REST API, inclui automaticamente descrições de endpoints e processos de negócio relacionados na descrição de cada endpoint, eliminando completamente a necessidade de o programador criar ou actualizar documentação.
Palavras finais
Todas as ferramentas de documentação API cobertas neste artigo são capazes de produzir documentação API de qualidade. É impossível declarar qualquer um dos instrumentos como sendo o maior. Toda a experiência e critérios de um software de documentação API são determinados pelas normas, conceitos, objectivos e requisitos de documentação do cliente.
