Começando com a documentação da API

Este guia guia você na publicação da sua primeira API no Document360, desde o upload do seu arquivo especulativo até um portal interativo e ao vivo para desenvolvedores.

Ao final deste artigo, você terá:

• Uma referência de API gerada a partir da sua especificação OpenAPI
• Seus endpoints visíveis e navegáveis pelos desenvolvedores
• O console interativo Try It! pronto para testes ao vivo da API

Pré-requisitos

Antes de começar, certifique-se de ter:

• Uma assinatura do Document360.
• Um arquivo de especificação de API em um desses formatos: OpenAPI 2.0, OpenAPI 3.0, OpenAPI 3.1 ou Postman Collection, seja como arquivo local (JSON, YML ou YML) ou hospedado em uma URL de onde você importará.
• Acesso ao portal da Base de Conhecimento com permissões para criar conteúdo.

Navegue até o espaço de trabalho de documentação da API

1. Faça login no Document360 e abra seu projeto no portal da Base de Conhecimento.
2. Na barra de navegação da esquerda, clique em documentação { }da API. Isso abre o espaço de trabalho dedicado da API, separado da sua base de conhecimento padrão.
3. Na barra de navegação superior, clique no menu suspenso Criar e selecione Nova API. Isso abre a janela de referência da Nova API.

Escolha como importar sua especificação

O Document360 suporta duas formas de importar seu arquivo de especificações: upload de arquivos e importação de URL. O fluxo CI/CD não é um método de importação separado; É uma forma de automatizar qualquer um desses dois métodos para que sua documentação seja atualizada automaticamente sempre que sua especificação mudar.

Faça upload da sua especificação

Faça upload de um arquivo

1. Na janela de referência da Nova API, selecione a opção Definir a API de Upload .
2. Clique em Upload do meu dispositivo ou arraste e solte seu arquivo. Formatos suportados: JSON, YAML, YML.
3. O Document360 analisa o arquivo e gera automaticamente a referência da API. Se avisos forem detectados, aparece uma seção de Alertas e Avisos — amplie-a para revisá-los. Você pode ver todos os detalhes mais adiante na seção de Registros.
4. Clique em Nova referência de API para prosseguir.

Importar a partir de uma URL

1. Na janela de referência da Nova API, selecione a opção Criar a partir da URL e clique em Próximo.
2. Insira a URL apontando para o seu arquivo de especificação OpenAPI no campo URL.
3. O Document360 busca e processa a especificação. Se avisos forem detectados, eles estarão disponíveis na seção de Logs após a importação.
4. Clique em Adicionar referência de API para prosseguir.

Use o fluxo CI/CD

1. Na janela de referência da Nova API, selecione a opção CI/CD Flow .
2. Copie o comando completo da CLI mostrado na janela.
3. No comando copiado, substitua o --path valor pelo caminho completo para seu arquivo de especificação local ou por uma URL válida apontando para ele. Por exemplo:

--path=/Users/yourname/projects/api/openapi.yaml

Ou uma URL:

--path=https://example.com/api/openapi.yaml

4. Cole o comando atualizado no seu terminal e pressione Enter. O Document360 faz upload da sua especificação e gera a documentação da API.

Sem arquivo de especificações? Use a API de Pet Store de exemplo

Se você não tiver um arquivo de especificação pronto, selecione Tentar o arquivo API da Pet Store de exemplo quando solicitado. O Document360 criará automaticamente uma referência de API de exemplo no modo rascunho. Você pode explorar e depois substituir por sua própria especialização.

Avisos e alertas de revisão

Após enviar sua especificação, o Document360 mostra um resumo de quantas categorias e artigos foram criados, junto com quaisquer alertas ou alertas detectados no seu arquivo.

• Alertas e alertas significam que a especificação foi importada, mas alguns elementos podem não aparecer como esperado. Você pode consultar todos os detalhes na seção de Logs: vá até a referência da sua API, clique no ícone Mais (⋯) e selecione Logs.
• Erros significam que a importação falhou. A causa mais comum é um formato de arquivo não suportado ou uma URL inválida. Substitua o arquivo ou corrija a URL e tente novamente.

Publique sua referência de API

Depois que sua especificação for processada com sucesso:

1. Uma janela de confirmação mostra o número de categorias e artigos criados. Clique em Publicar para ativar a referência da API.
2. Se quiser revisar o conteúdo antes de publicar, clique em Fechar. Sua referência de API é salva no modo rascunho e visível no painel Categorias & Artigos.

Configure a autenticação para o Try It!

O console Try It! permite que os desenvolvedores testem seus endpoints de API diretamente pela documentação. Para que funcione corretamente, o método de autenticação deve estar definido na sua especificação e configurado no Document360.

O Document360 suporta os seguintes métodos de autenticação:

OAuth2 e OpenID Connect: configuração adicional

Ao usar OAuth2 ou OpenID Connect, são necessárias duas configurações:

• Redirecionar URI — Defina isso no seu provedor OAuth para domain/oauth. Por exemplo: https://apidocs.yourdomain.com/oauth.
• Renovação silenciosa — O Document360 atualiza automaticamente o token de autorização em segundo plano durante sessões ativas do Try It!, para que os usuários não precisem se autenticar manualmente.

Definir acesso e privacidade do leitor

Controle quem pode ver sua referência de API publicada configurando as configurações de acesso ao leitor.

Para configurar o acesso do leitor, navegue até Configurações > Usuários e Permissões > Acesso ao Leitor no portal da Base de Conhecimento e localize o espaço de trabalho da documentação da sua API.