A migração de APIs gerenciadas pelo Swagger para Apidog envolve vários métodos. Este guia apresentará 4 maneiras simples de exportar o arquivo Swagger para importá-lo no Apidog, utilizando links online para importações agendadas, utilizando o plugin IDEA para uploads com um clique, e realizando a importação através da Open API. Abaixo estão os passos detalhados para cada método.
Método 1: Exportar o Arquivo Swagger e Importá-lo no Apidog
Esta é a abordagem mais direta, adequada para migrações únicas, especialmente quando sua documentação de API está estável. Aqui estão os passos específicos:
Passo 1. Exportar o Arquivo Swagger
No Swagger UI, exporte sua documentação de API como um arquivo .yaml ou .json. Normalmente, você pode encontrar uma opção para baixar o arquivo no canto superior esquerdo do Swagger UI.
Se a interface não mostrar um link URL, você pode abrir o console do navegador pressionando “F12” ou “Ctrl+Shift+I”, então navegue até Rede -> Buscar/XHR e atualize a página. Isso deve revelar um arquivo .json que você pode abrir em uma nova janela e baixar.
Passo 2. Importar Documentos Swagger no Apidog
Abra o Apidog, navegue até seu projeto e selecione Configurações do Projeto -> Importar Dados -> OpenAPI/Swagger. Faça o upload do arquivo .yaml ou .json exportado anteriormente. Se você tiver uma URL de arquivo fonte publicamente acessível, você também pode importá-lo via URL.
Após o upload, o Apidog irá automaticamente analisar e importar sua documentação de API, e você poderá editá-la e gerenciá-la ainda mais na interface de pré-visualização.
Método 2: Importação Agendada via Link Online
Se a documentação da sua API Swagger é atualizada com frequência, exportações e importações manuais podem se tornar trabalhosas. Nesse caso, você pode utilizar o recurso de importação agendada do Apidog para sincronizar automaticamente o documento Swagger online. Aqui estão os passos:
Passo 1. Obter o Link Online
Certifique-se de que seu documento Swagger possa ser acessado via uma URL pública.
https://petstore.swagger.io/v2/swagger.jsonPasso 2. Configurar Tarefa Agendada para Importar Documentos OpenAPI
No Apidog, navegue até o projeto onde você deseja configurar a importação agendada, selecione Configurações do Projeto -> Importar Dados -> Importação Agendada e crie uma nova tarefa. Insira a URL do documento Swagger online (URL da fonte de dados) e defina o intervalo de importação (por exemplo, a cada 3 horas, a cada 12 horas, etc.).
Após salvar, o Apidog irá buscar e atualizar automaticamente a documentação mais recente da API com base no intervalo especificado.
Método 3: Upload com Um Clique via Plugin IDEA
O plugin Apidog IDEA reconhece o código-fonte de projetos Java e Kotlin locais, gera automaticamente a documentação da API e sincroniza-a com seu projeto Apidog. Ele suporta estruturas comuns, como Spring Boot, permitindo uma experiência de código verdadeiramente sem intrusões.
Para tornar o processo de migração mais eficiente, aqui estão os passos para usar o plugin IDEA:
Passo 1. Instalar o Plugin Apidog IDEA
Abra o IntelliJ IDEA (versão 2019.3 ou superior), vá em Configurações -> Plugins, pesquise por “Apidog Helper” e instale-o. Reinicie o IDEA após a instalação.
Passo 2. Configurar o Token de Acesso da API
No Apidog, clique na sua foto de perfil no canto superior direito e selecione Configurações da Conta -> Token de Acesso da API. Gere um token de acesso da API aqui e defina seu período de validade conforme necessário.
No IDEA, abra a configuração do plugin "Apidog Helper", insira o token de acesso da API e clique em “Testar Token.” Se for bem-sucedido, salve a configuração clicando em “Aplicar” ou “OK.”
Passo 3. Sincronizar API
Clique com o botão direito do mouse no nó do módulo na árvore de diretórios do seu projeto e selecione “Enviar para Apidog” para sincronizar todas as interfaces dentro do módulo. Alternativamente, abra o arquivo Controller, clique com o botão direito e selecione “Enviar para Apidog” para sincronizar todas as interfaces dentro do Controller.
Na primeira sincronização, um diálogo de configuração solicitará que você selecione a equipe e o projeto relevantes, e as interfaces serão carregadas no diretório raiz do projeto por padrão.
Passo 4. Visualizar a Documentação da API
Uma vez que a sincronização seja bem-sucedida, abra o Apidog para visualizar a documentação da API gerada automaticamente.
Método 4: Importar via Open API
O Apidog fornece uma API aberta que permite aos desenvolvedores importar diretamente os dados da API em formato Swagger/OpenAPI através da API, e a documentação da API aberta está disponível em https://openapi.apidog.io/.
Abaixo estão os passos para importar via Open API:
Passo 1. Obter Token de Acesso da API
No Apidog, clique na sua foto de perfil no canto superior direito e selecione Configurações da Conta -> Token de Acesso da API para gerar um token de acesso da API (access_token) para autenticação. Ajuste o período de validade do token conforme necessário.
Passo 2. Obter o ID do Projeto
No Apidog, navegue até Configurações do Projeto -> Configurações Básicas para visualizar seu ID do projeto. O ID do projeto é um identificador exclusivo para cada projeto e é necessário ao chamar a API para garantir que os dados sejam importados para o projeto correto.
Passo 3. Chamar a Open API
Para importar dados em formato OpenAPI/Swagger para o Apidog, você pode chamar o seguinte endpoint: https://api.apidog.com
Parâmetros de Path
| Nome do Parâmetro | Tipo de Parâmetro | Necessário | Descrição |
|---|---|---|---|
| projectId | String | Necessário | ID do projeto, usado para especificar o projeto-alvo para a importação de dados. |
| Exemplo: | https://api.apidog.com/v1/projects/3760990/import-openapi |
Parâmetros de Corpo
| Nome do Parâmetro | Tipo de Parâmetro | Necessário | Descrição |
|---|---|---|---|
| input | String/Objeto | Necessário | Dados OpenAPI/Swagger a serem importados, pode ser uma string JSON/YAML ou uma URL encapsulada em um objeto. |
| options | Objeto | Opcional | Opções avançadas para definir o ID do diretório de destino, comportamento de sobrescrição da interface de importação, etc. Os parâmetros relevantes podem ser visualizados em detalhes na documentação da Open API do Apidog. |
Exemplo de Corpo da Solicitação:
{
"input": {
"url": "https://petstore.swagger.io/v2/swagger.json"
},
"options": {
"endpointOverwriteBehavior": "CREATE_NEW",
"endpointCaseOverwriteBehavior": "CREATE_NEW",
"updateFolderOfChangedEndpoint": false
}
}
inputSe você fornecer diretamente uma string de dados OpenAPI, pode passá-la no seguinte formato. A string pode estar no formato JSON, YAML ou X-YAML:
{
"input": "{'openapi':'3.0.0','info':{'title':'API de Amostra','version':'1.0.0'},'paths':{'/sample':{'get':{'summary':'Endpoint de Amostra','responses':{'200':{'description':'operação bem-sucedida'}}}}}}"
}
Se você fornecer uma URL publicamente acessível que aponte para dados em formato OpenAPI/Swagger, pode passá-la no seguinte formato:
{
"input": {
"url": "https://petstore.swagger.io/v2/swagger.json"
}
}
Se a fonte de dados exigir autenticação, você também pode fornecer informações de autenticação Básica para autenticação:
{
"input": {
"url": "https://petstore.swagger.io/v2/swagger.json",
"basicAuth": {
"username": "apiUser",
"password": "securePassword123"
}
}
}
Parâmetros de Cabeçalho
Além dos parâmetros necessários mencionados acima, informações relevantes de autenticação também devem ser incluídas no cabeçalho da solicitação, da seguinte forma:
| Nome do Parâmetro | Tipo de Parâmetro | Necessário | Descrição |
|---|---|---|---|
| X-Apidog-Api-Version | String | Necessário | Número da versão da Open API; a versão atualmente suportada é 2024-03-28. |
| Authorization | String | Necessário | Formato de autenticação; deve ser Bearer seguido pelo token de acesso pessoal obtido no passo 1. |
Exemplo:
'X-Apidog-Api-Version': '2024-03-28'
'Authorization': 'Bearer APS-OVWel6j5103zaaaaaaQle99fGNBw8ucH'
Exemplo de Resposta
Após uma chamada de API bem-sucedida, uma resposta JSON semelhante à seguinte será retornada, contendo estatísticas do processo de importação, como o número de interfaces criadas, atualizadas e ignoradas, bem como o número de modelos de dados criados e atualizados. Se uma mensagem de erro for retornada, verifique cuidadosamente se algum parâmetro necessário está ausente ou se o formato dos dados importados está correto.
{
"data": {
"counters": {
"endpointCreated": 20,
"endpointUpdated": 0,
"endpointIgnored": 0,
"endpointFailed": 0,
"endpointFolderCreated": 3,
"endpointFolderUpdated": 0,
"endpointFolderIgnored": 0,
"endpointFolderFailed": 0,
"schemaCreated": 0,
"schemaUpdated": 7,
"schemaIgnored": 0,
"schemaFailed": 0,
"schemaFolderCreated": 0,
"schemaFolderUpdated": 0,
"schemaFolderIgnored": 0,
"schemaFolderFailed": 0
}
}
}Passo 5. Visualizar Resultados da Importação
Após completar a importação, você pode visualizar a documentação da API gerada no projeto correspondente do Apidog. Para mais informações detalhadas sobre os parâmetros de entrada e mensagens de resposta, consulte a documentação da Open API do Apidog.
Perguntas Frequentes
- O que fazer se ocorrer um erro durante a importação do arquivo? Se você receber um erro de análise ao importar um arquivo
.yaml, isso indica que o arquivo não está em conformidade com as especificações do OpenAPI e precisa ser modificado. Você pode enviar o arquivo para Swagger Editor para diagnosticar erros. Após resolver qualquer problema, tente a importação novamente.
Conclusão
Com os quatro métodos descritos acima, você pode facilmente migrar suas APIs gerenciadas pelo Swagger para o Apidog. Cada método é adequado para cenários diferentes, permitindo que você escolha o mais apropriado com base em suas necessidades. Seja através de importação manual, sincronização online agendada, uploads de plugins ou integração com Open API, o Apidog fornece uma experiência eficiente e conveniente de gerenciamento de APIs.