Como criar documentação de API no Postman?

how create api documentation postman

Este tutorial explica como criar uma documentação estilizada e de boa aparência com o mínimo de esforços usando o suporte de documentação de API fornecido pela ferramenta Postman:

Para qualquer API, seja interna ou voltada ao público, a documentação é um dos ingredientes mais essenciais para seu sucesso.

A principal razão para isso é que a documentação é a maneira como você se comunica com seus usuários.

• Como sua API deve ser usada?
• Todos os códigos de status são suportados?
• Quais são os códigos de erro?
• Quais são os tipos de métodos expostos?

Todas essas informações são necessárias para que qualquer pessoa use ou implemente a API para a necessidade desejada.

=> Cuidado com a série de treinamento do carteiro simples aqui.

melhor servidor uau para novos jogadores 2017

O Postman fornece uma metodologia de documentação fácil de usar e, para documentação básica, é tão simples quanto clicar em um botão na coleção do Postman e você pode obter o URL público para a documentação da API.

O que você aprenderá:

• Criação de documentação de API no Postman
  • Recursos de documentação
  • Criando Documentação
• Conclusão
  • Leitura recomendada

Criação de documentação de API no Postman

Recursos de documentação

Os principais recursos do gerador de documentação Postman incluem:

• Suporta sintaxe markdown. Markdown é uma sintaxe de documentação genérica, que você geralmente deve ter notado em qualquer projeto Github. Permite tornar o estilo e a formatação do texto mais familiares e fáceis.
• Nenhuma sintaxe / requisitos específicos para a criação de documentação. As informações de solicitação e coleta são utilizadas da melhor forma para gerar documentação.
• Ele pode ser publicado em um URL público ou em um domínio personalizado (para usuários corporativos).
• Gera snippets de código para fazer chamadas para a API em diferentes linguagens como C #, PHP, Ruby, Python, Node, etc.

Criando Documentação

O gerador de documentos Postman refere-se à coleção, pasta e descrição de solicitação individual e os agrupa ao criar ou gerar documentação para a coleção.

Ele faz uso de vários parâmetros de solicitação como cabeçalhos, parâmetros de string de consulta, parâmetros de formulário e indica o uso desses valores na documentação da solicitação.

Aqui está um tutorial em vídeo:

Vamos criar uma coleção básica com 3 solicitações usando a mesma API de teste de nossos outros artigos. Adicionaremos algumas informações à descrição da coleção, bem como às solicitações individuais e também criaremos algumas solicitações e respostas de exemplo, que também serão capturadas durante a criação da documentação.

Siga as etapas abaixo para adicionar informações básicas sobre as solicitações e, em seguida, criar a documentação.

# 1) Crie uma coleção com 3 solicitações, ou seja, registrar usuário, fazer login e obter usuário (consulte aqui para cargas úteis de solicitação e URLs de API).

#dois) Agora vamos adicionar algumas informações em formato de redução à coleção. Markdown é um formato padrão que é usado para quase toda a documentação no Github (para mais informações sobre markdown, consulte aqui )

Adicionaremos algumas informações à descrição da coleção no formato de redução conforme abaixo.

Para visualizar a aparência do markdown, consulte o portal da web de código aberto aqui.

# 3) Agora adicionaremos as descrições às solicitações individuais da coleção. Semelhante à coleção, o formato de redução também é compatível com as descrições de solicitação (para obter informações mais detalhadas sobre o guia de redução, consulte aqui )

Vejamos um exemplo de uma das solicitações de endpoint de registro de usuário (o mesmo pode ser aplicado a outras solicitações).

Texto Markdown:

Visualização do Markdown:

# 4) Para todos os endpoints da API, vamos capturar ou salvar um exemplo que seria usado pelo gerador de documentação.

Um exemplo nada mais é do que um exemplo de solicitação-resposta para a solicitação da API em consideração. Salvar a resposta como um exemplo permite que o gerador de documentação a capture como parte da própria documentação.

Para salvar um exemplo, clique no 'Mandar' botão para executar a solicitação e na guia de resposta, clique Salvar resposta -> Salvar como exemplo .

Depois que o exemplo é salvo, ele é persistido na coleção e pode ser acessado a qualquer momento no futuro por meio de um Exemplos link no construtor de solicitações.

# 5) Depois que todas as informações acima forem adicionadas, vamos ver como criar uma visualização da documentação.

Abra as opções de coleção e clique em “ Publicar documentos ”.

Observação: Uma coisa importante a se notar aqui é que apenas usuários registrados no Postman poderão usar o recurso Publicar documentos no Postman. O registro é gratuito, mas deve ser feito através do seu e-mail. Existem outros recursos / recursos, como compartilhamento de coleções e áreas de trabalho, criação de monitores, etc., que são adicionados às contas registradas.

# 6) Uma vez ' Publicar documentos ”For executado, uma guia do navegador será aberta com os detalhes da coleção do Postman (internamente o Postman hospeda essa coleção em seus próprios servidores, além do sistema de arquivos local do usuário).

Clique em “Antevisão” para ver a documentação antes de ser publicada.

' Publicar coleção ”Link publicará a documentação em um URL acessível publicamente. Geralmente, não é recomendado publicar APIs com informações confidenciais de autorização para publicar no URL público. Essas APIs podem ser publicadas usando domínios personalizados com contas corporativas do Postman.

# 7) Vamos ver como fica a visualização da documentação. Clicar em “ Pré-visualizar a documentação ”Abre a documentação em um modo de visualização hospedado nos servidores do Postman. Vamos ver quais detalhes diferentes são capturados na documentação (conforme configuramos em locais diferentes. Por exemplo , descrição da coleção, descrição da solicitação e exemplos).

Nas 2 capturas de tela acima, você pode ver que todas as informações que foram adicionadas à coleção e as descrições da solicitação são capturadas de forma estilizada na visualização da documentação.

api testando perguntas e respostas da entrevista

Além disso, a documentação, por padrão, fornece ligações de idioma conforme destacado e isso torna muito mais fácil para alguém que deseja fazer a solicitação de API diretamente no idioma listado.

# 8) Ele também permite que você execute modificações de estilo muito básicas, como mudar a cor de fundo, mudar a cor de fundo e de primeiro plano dos modelos de cabeçalho, etc. Mas, no geral, a visualização padrão em si é suficiente para publicar um conjunto realmente bom de documentação capturando muitos detalhes importantes sobre a API.

Conclusão

Neste tutorial, examinamos o suporte de documentação da API fornecido pelo Postman, com o qual podemos criar uma documentação estilizada e de boa aparência com o mínimo de esforço.

Ele também permite muitos bons modelos e estilos definidos pelo usuário que podem ser aplicados aos documentos gerados e permite a publicação de documentação em um URL público.

Para terminais de API privados, também há uma provisão para publicar documentação em um domínio personalizado que pode ser configurado para contas corporativas ou usuários.

Leitura adicional = >> Como publicar o contrato do pacto para o corretor do pacto

=> Visite aqui para aprender Postman From Scratch.

Leitura recomendada

• Tutorial POSTMAN: Teste de API usando POSTMAN
• Como e quando usar os scripts de pré-solicitação e pós-solicitação do Postman?
• Como usar o Postman para testar diferentes formatos de API?
• Como usar a integração de linha de comando com o Newman no Postman?
• Tutorial da API Rest: Arquitetura e restrições da API REST
• Gere documentação viva com Pickles para arquivos de recurso Specflow
• Automatizando a validação de resposta com afirmações no carteiro
• Códigos de resposta da API Rest e tipos de solicitações de descanso