Guia Definitivo: Hospedando Documentação de API em um Domínio Personalizado

No mundo competitivo do desenvolvimento de software, entregar documentação da API clara e acessível é essencial para permitir a integração e adoção contínuas de seus serviços. Uma maneira eficaz de aumentar a acessibilidade e o profissionalismo de sua documentação da API é hospedá-la em um domínio personalizado. Este guia irá orientá-lo através dos benefícios e etapas envolvidas na configuração da sua documentação da API com um domínio personalizado.

Importância do Domínio Personalizado para a Documentação da API

A documentação da API é um componente crítico para os desenvolvedores que dependem de suas APIs para construir aplicações. Hospedar essa documentação em um domínio personalizado não apenas reforça a identidade da sua marca, mas também proporciona uma experiência amigável e profissional para seus usuários. Ao usar um domínio personalizado, você pode garantir que sua documentação da API seja facilmente acessível e reflita a qualidade de seu serviço.

💡

Apidog se destaca como a plataforma ideal para documentação completa da API, oferecendo suporte de ponta a ponta desde o design até a auto-geração e hospedagem - tudo disponível na versão gratuita do Apidog. Experimente hoje!

botão

Benefícios de Hospedar a Documentação da API em um Domínio Personalizado

Consistência de Marca

Um domínio personalizado permite alinhar sua documentação da API com a identidade da sua marca. Isso cria uma experiência coesa para seus usuários, reforçando a credibilidade e o profissionalismo da sua marca.

Acessibilidade Aprimorada

Usar um domínio personalizado torna sua documentação da API mais fácil de lembrar e acessar. Em vez de uma URL genérica ou longa, os usuários podem navegar rapidamente para um domínio com a marca, melhorando a experiência geral do usuário.

Segurança Aprimorada

Domínios personalizados geralmente vêm com recursos de segurança aprimorados, como certificados SSL, que protegem os dados dos seus usuários e criam confiança em seu serviço. A hospedagem segura da documentação garante que os usuários possam acessar e interagir com sua documentação da API com segurança.

Benefícios de SEO

Um domínio personalizado pode melhorar suas classificações nos motores de busca, tornando sua documentação mais descoberta. Ao otimizar sua documentação da API para motores de busca, você pode atrair mais desenvolvedores para a sua plataforma.

Etapas para Hospedar a Documentação da API em um Domínio Personalizado

Passo 1. Escolha uma Plataforma de Hospedagem de Documentação

Várias plataformas, como SwaggerHub, Redocly e Apidog, permitem que você hospede a documentação da API. Escolha uma que atenda suas necessidades e suporte a configuração de domínio personalizado.

Passo 2. Configure Seu Domínio Personalizado

Depois de escolher uma plataforma, siga estas etapas gerais para configurar seu domínio personalizado:

a. Compre um Nome de Domínio: Se você ainda não tiver um domínio, compre um de um registrador de domínio como GoDaddy, Namecheap ou Google Domains.

b. Configure as Configurações de DNS: Faça login no seu registrador de domínio e navegue até a seção de gerenciamento de DNS. Crie um registro CNAME que aponte seu domínio personalizado para o domínio da plataforma de hospedagem da documentação. Por exemplo, se sua documentação estiver hospedada em docs.suaapi.com, crie um registro CNAME apontando docs.suaapi.com para suaapi.docs.plataformadehospedagem.com.

c. Verifique a Propriedade do Domínio: Algumas plataformas exigem que você verifique a propriedade do domínio. Este processo geralmente envolve adicionar um registro TXT às suas configurações de DNS com um código de verificação fornecido pela plataforma.

d. Configure HTTPS (SSL): Garanta que seu domínio personalizado suporte HTTPS para conexões seguras. Muitas plataformas de hospedagem oferecem certificados SSL automáticos, mas você pode precisar configurá-los manualmente em alguns casos.

Passo 3. Implemente Sua Documentação da API

Com seu domínio configurado, implemente sua documentação da API na plataforma de hospedagem. Siga as instruções específicas da plataforma para fazer o upload dos seus arquivos de documentação ou conectar seu repositório.

Passo 4. Teste e Verifique

Uma vez implementada, acesse sua documentação da API através do seu domínio personalizado para garantir que tudo esteja funcionando corretamente. Verifique se há links quebrados, problemas de formatação ou erros de certificado SSL.

Projete, Auto-Gere e Hospede a Documentação da API usando Apidog

Na economia digital, APIs (Interfaces de Programação de Aplicações) são cruciais para permitir que aplicações de software se comuniquem entre si. Seja você uma startup ou uma empresa, uma documentação robusta da API é essencial para ajudar os desenvolvedores a entender e usar suas APIs de forma eficiente.

Entre todas as plataformas de hospedagem de documentação da API, Apidog se destaca como uma plataforma versátil que suporta todo o ciclo de vida da documentação da API - desde o design até a auto-geração e a hospedagem. Aqui está o motivo pelo qual deve ser sua ferramenta de referência.

1. Ferramenta Abrangente de Design de API

Apidog oferece uma ferramenta de design robusta que permite criar especificações detalhadas de API. Se você está começando do zero ou refinando uma API existente, a ferramenta de design do Apidog oferece:

Interface Visual: Uma interface intuitiva de arrastar e soltar para projetar pontos finais da API, esquemas de solicitação/resposta e modelos de dados.
Conformidade com Padrões: Garante automaticamente que seus designs de API atendam aos padrões da indústria, como OpenAPI e Swagger.
Design Colaborativo: Permite que membros da equipe colaborem em tempo real, garantindo que o design da sua API evolua com contribuições coletivas.

2. Auto-Gerar Documentação

Um dos recursos destaque do Apidog é sua capacidade de auto-gerar documentação da API diretamente a partir de suas especificações de API. Isso garante que sua documentação esteja sempre atualizada e consistente com o estado atual da sua API.

Síncronização: Atualiza automaticamente a documentação sempre que mudanças são feitas no design da API.
Documentação Rica: Inclui descrições detalhadas, modelos de dados, exemplos de solicitações e respostas, e métodos de autenticação.
Personalização: Permite que você adicione notas personalizadas usando markdown, exemplos de código e metadados para aprimorar a documentação.

3. Documentação Interativa da API

Apidog suporta documentação interativa, permitindo que os desenvolvedores testem pontos finais da API diretamente da própria documentação. Esse recurso prático melhora a experiência do desenvolvedor e torna mais provável que eles adotem e usem sua API:

Recurso Experimente: Permita que os desenvolvedores executem solicitações da API e visualizem respostas diretamente dentro da documentação online.
Gerenciamento de Autenticação: Gerencia chaves de API, tokens e outros métodos de autenticação de forma perfeita.

4. Hospedagem Fácil e Domínios Personalizados

Apidog não apenas ajuda você a projetar e gerar documentação, mas também oferece soluções robustas de hospedagem. Você pode hospedar sua documentação em um domínio personalizado, melhorando o profissionalismo da sua marca e centralizando seus recursos.

Domínios Personalizados: Hospede sua documentação em um domínio que alinhe com sua marca (por exemplo, docs.suaempresa.com).
Segurança: Fornece criptografia SSL, autenticação de usuários e gerenciamento de permissões para manter sua documentação segura.

5. Integração Perfeita com Ferramentas de Desenvolvimento

Apidog se integra perfeitamente com várias ferramentas de desenvolvimento e CI/CD para agilizar seu fluxo de trabalho. Essa compatibilidade garante que sua documentação faça parte do seu ciclo de vida de desenvolvimento mais amplo:

Sistemas de Controle de Versão: Integra-se com GitHub, GitLab e Bitbucket.
Pipelines de CI/CD: Compatível com Jenkins, CircleCI e outras ferramentas de CI/CD.

6. Recursos Robustos de Colaboração

Para equipes, a colaboração é fundamental para manter a documentação precisa e abrangente. Apidog suporta múltiplos colaboradores e fornece recursos para garantir que as mudanças sejam rastreadas e gerenciadas de forma eficiente:

Edição em Tempo Real: Vários membros da equipe podem trabalhar na documentação simultaneamente.
Controle de Versão: Rastreie alterações, volte a versões anteriores e gerencie atualizações da documentação sem problemas.

Usando Domínio Personalizado para a Documentação da API no Apidog

Apidog oferece a capacidade de usar um domínio personalizado para sua documentação da API. Aqui está um guia passo a passo sobre como você pode fazer isso:

Passo 1. Iniciando a Configuração do Domínio Personalizado para a Documentação da API

Os domínios personalizados podem ser configurados por usuários com acesso de proprietário ou administrador. Siga estas etapas para começar:

1. Acesse o Módulo de Compartilhamento

Navegue até o módulo de compartilhamento do projeto no Apidog.

clique no menu Compartilhar Documentos na barra lateral.
Vá para a página de configurações de Publicação no menu secundário.

Página de configurações de publicação da documentação da API do Apidog

2. Iniciar Configuração do Domínio Personalizado

Na seção Domínio Personalizado, clique no botão Editar.

Você verá duas opções para definir um domínio personalizado:

CNAME: Recomendado por sua simplicidade e flexibilidade.
Proxy Reverso: Mais avançado, adequado para usuários familiarizados com configurações de CDN ou proxy reverso.

Opções de domínio personalizado para documentação da API no Apidog

Passo 2. Configurar Domínio Personalizado para Documentação da API

Método 1: Configurando Domínio Personalizado usando CNAME

1. Configure um Registro CNAME

A configuração de DNS acontece no painel de controle do seu provedor de DNS. Aqui está um guia genérico:

Tipo: Escolha CNAME.
Nome ou entrada DNS: Insira seu subdomínio (por exemplo, docs.exemplo.com ou apenas docs se o domínio for implícito).
Destino ou valor ou destino: Este é o local para onde o subdomínio deve apontar, que pode ser encontrado nas configurações de publicação do Apidog quando você escolher a opção CNAME. Ele terá um formato semelhante a: {projectId}.apidog.io (por exemplo, 12345678.apidog.io).
TTL (Time To Live): Defina como Automático ou deixe o valor padrão se não tiver certeza.

Configurar CNAME DNS para domínio personalizado

Certifique-se de que não existam registros conflitantes (como A, AAAA, TXT) para o subdomínio escolhido. Remova-os se necessário antes de adicionar seu registro CNAME.

Nota Especial para Usuários do Cloudflare:

Se estiver usando Cloudflare:

Certifique-se de que o proxy do Cloudflare esteja desativado.
Isso impede a ofuscação do destino do DNS e permite que o Apidog execute verificações rotineiras de domínio.

2. Aguardando a Propagação do DNS

As mudanças de DNS normalmente levam entre 10 minutos a 48 horas para se propagar. Para rastrear o progresso, você pode usar uma ferramenta de pesquisa de DNS como WhatsMyDNS. Insira seu subdomínio, escolha CNAME e clique em buscar para ver atualizações da propagação em tempo real.

Método 2: Configurar Domínio Personalizado Usando um CDN

Esta etapa é relevante se você escolher a opção Proxy Reverso.

Escolhendo Proxy Reverso para configurar domínio personalizado

1. Configurando o AWS CloudFront como Proxy Reverso

Você pode usar o AWS CloudFront ou outros serviços de CDN como seu servidor proxy reverso. Usaremos o AWS CloudFront como servidor proxy reverso neste exemplo.

Faça login no AWS e navegue até o CloudFront. Clique em Criar Distribuição.

Configure as configurações de distribuição:

Nome do Domínio de Origem: {projectId}.apidog.io
Nome: Uma descrição da origem, que deve ser única, permitindo que você diferencie entre várias origens dentro da mesma distribuição.
Política de Protocolo de Origem: Defina como Somente HTTP.
Nomes de Domínio Alternativos (CNAMEs): O nome do seu domínio personalizado.
Certificado SSL: Escolha o certificado SSL do AWS Certificate Manager (ACM).

Cabeçalhos Personalizados de Origem:

Nome do Cabeçalho: X-Apidog-Project-ID
Valor: {projectId}

Configurações Padrão de Comportamento de Cache:

Política de Protocolo do Visualizador: Redirecionar HTTP para HTTPS
Métodos HTTP Permitidos: Selecione GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
Configurações de cache e solicitação de origem: Use configurações de cache legadas, selecionando Tudo para Cabeçalhos, Strings de Consulta e Cookies.

2. Concluir a Criação da Distribuição:

Clique em Criar Distribuição na parte inferior da página. O status da distribuição será exibido como "Em progresso" até ser implantado.

3. Configuração de DNS:

Adicione um registro CNAME no painel de controle do seu provedor de DNS apontando para o nome do domínio CloudFront.

Método 3: Configurar Domínio Personalizado Usando Servidor Proxy Reverso

Para usuários configurando seu servidor proxy reverso, aqui está como configurar o Nginx:

1. Configuração do Nginx:

server {
    ...
    location / {
        proxy_pass  http://{projectId}.apidog.io;
        proxy_set_header X-Apidog-Project-ID {projectId};
        proxy_set_header Host docs.exemplo.com;
        ...
    }
    ...
}

Exemplo de configuração do Caddy:

:8080 {
        handle_path /* {
                reverse_proxy http://{projectId.apidog.io {
                        header_up X-Apidog-Project-ID {projectId}
                        header_up Host "docs.exemplo.com"
                }

      }
}
}

2. Configure o Registro DNS:

Configure o registro DNS para o seu nome de domínio personalizado para apontar para o seu servidor proxy reverso.

Método 4: Configurar Domínio Personalizado Embutindo em um Subdiretório do Seu Próprio Domínio

Disponível na versão do Apidog ≥ 2.5.24. Você pode embutir a documentação da API em um subdiretório (por exemplo, Seu-Site.com/api-docs).

1. Ative o Proxy Reverso no Apidog:

Vá para as configurações de Domínio Personalizado.
Clique em Proxy Reverso e ative Usar subdiretório.

Ativar proxy reverso no Apidog e ativar uso de subdiretório

2. Modifique a Configuração do Servidor Web (por ex. Nginx):

server {
    ...
    location /api-docs/ {
        proxy_pass  http://{projectId}.apidog.io/;
        proxy_set_header X-Apidog-Project-ID {projectId};
        proxy_set_header Host docs.exemplo.com;
        ...
    }
    ...
}

Melhores Práticas para Documentação da API

Branding Consistente: Certifique-se de que seu domínio personalizado e o conteúdo da sua documentação da API estejam alinhados com o estilo e a mensagem da sua marca.
Seja Abrangente: Inclua explicações detalhadas, exemplos de código e casos de uso.
Forneça Navegação Clara: Garanta que sua documentação seja fácil de navegar com uma estrutura clara e funcionalidade de busca.
Atualizações Regulares: Mantenha sua documentação atualizada com as últimas mudanças e melhorias da API.
Monitoramento: Monitore regularmente seu domínio personalizado para qualquer problema ou tempo de inatividade para manter uma experiência de usuário contínua.
Feedback dos Usuários: Incentive os usuários a fornecer feedback sobre sua documentação para melhorar continuamente sua clareza e usabilidade.

Conclusão

No campo altamente competitivo do desenvolvimento de software, fornecer documentação da API clara e acessível é crucial para a integração e adoção contínuas de seus serviços. Hospedar sua documentação da API em um domínio personalizado oferece inúmeros benefícios, incluindo maior consistência de marca, acessibilidade aprimorada, segurança aumentada e melhor desempenho de SEO. Seguindo os passos descritos neste guia, você pode facilmente configurar e implantar sua documentação da API em um domínio personalizado, melhorando assim a experiência do usuário e reforçando o profissionalismo da sua marca.

Plataformas como Apidog tornam esse processo ainda mais simples, oferecendo ferramentas abrangentes para projetar, auto-gerar e hospedar a documentação da API. Com recursos como uma interface de design robusta, documentação interativa, integração perfeita com ferramentas de desenvolvimento e fortes capacidades de colaboração, o Apidog se destaca como uma solução versátil para gerenciar suas necessidades de documentação da API.

Por fim, investir em um domínio personalizado para sua documentação da API não apenas eleva a percepção do seu serviço, mas também garante que os desenvolvedores possam acessar e utilizar suas APIs de forma eficiente. Ao priorizar uma documentação de qualidade e aproveitar ferramentas como o Apidog, você pode fomentar uma maior confiança e engajamento com sua comunidade de desenvolvedores, impulsionando o sucesso e a adoção de suas APIs.