La documentación de API profesional merece un dominio profesional. De forma predeterminada, la documentación de Apidog es accesible en un dominio <subdomain>.apidog.io. Sin embargo, puede personalizar esto configurando su propio dominio, lo que permite que su audiencia acceda a la documentación en un dominio alineado con la marca de su organización.Requisitos previos#
Antes de configurar un dominio personalizado, asegúrese de tener:Permisos de administrador para el proyecto de Apidog
Propiedad o control del dominio que desea usar
Acceso a la configuración DNS de su dominio
(Para el método de proxy inverso) Familiaridad con la configuración de CDN o proxy inverso
Iniciar la configuración del dominio personalizado#
Para acceder a la configuración del dominio personalizado, vaya al menú Publish Docs en la barra lateral y luego diríjase a la página de configuración Publish. Encontrará una sección Custom Domain donde puede hacer clic en el botón Edit para comenzar la configuración.Métodos de configuración de dominio personalizado#
Existen dos tipos de opciones para configurar un dominio personalizado:1.
CNAME (Recomendado): La opción más fácil de configurar y mantener; funciona tanto para subdominios como para dominios raíz, lo que proporciona la máxima flexibilidad.
2.
Reverse Proxy (Avanzado): Requiere usar una red de entrega de contenido (CDN) o configurar un proxy inverso en su propio servidor; se recomienda para usuarios familiarizados con estas tecnologías.
Configurar CNAME#
Esta sección solo es aplicable si seleccionó la opción CNAME en el paso anterior.
1.
Configurar un registro CNAME
2.
Esperar a que los cambios surtan efecto
Configurar un registro CNAME#
Los nombres de los campos y los pasos de configuración pueden diferir entre paneles de control DNS, pero los conceptos principales siguen siendo los mismos. Si tiene dudas, verifíquelo con su proveedor de DNS.El type es el tipo de registro DNS que desea crear. Aquí, debe elegir CNAME.
El name o DNS entry es donde introduce su subdominio. Es posible que deba introducirlo completo (por ejemplo, docs.example.com) o que solo deba introducir la parte anterior a su dominio ápice (por ejemplo, docs). Si no está seguro de cuál usar, consulte con su proveedor de DNS.
El target, value o destination es donde debe apuntar el subdominio. Debería ver el valor correspondiente en la configuración de Publish en Apidog cuando elija la opción DNS CNAME. Tendrá un aspecto similar a {docsSiteId}.apidog.io. Debe introducir este valor completo (por ejemplo, 12345678.apidog.io).
También puede ver un campo llamado TTL, que significa Time To Live. Es el número de segundos durante los cuales se puede almacenar en caché el registro DNS. Si no está seguro de qué configurar, le sugerimos seleccionar Auto o mantener el valor predeterminado.
Un registro CNAME no puede coexistir con otro registro para el mismo nombre. Si ya tiene un registro A, un registro AAAA, un registro TXT o cualquier otro tipo de registro para el subdominio elegido, deberá eliminarlos primero, antes de añadir el registro CNAME.
Si está configurando DNS en el panel de control de Cloudflare, asegúrese de que el proxy de Cloudflare (la nube naranja, también llamado "Proxy status" en la configuración de su dominio) esté deshabilitado. Esto se debe a dos motivos:Esta opción oculta al público el destino DNS de su dominio, lo que impide que Apidog ejecute correctamente las comprobaciones rutinarias en su dominio personalizado.
Su dominio personalizado ya se beneficiará de CDN.
¿Cuánto tiempo tardan los cambios en surtir efecto?#
La respuesta breve: es posible que deba esperar entre 10 minutos y 48 horas para que los cambios DNS surtan efecto antes de pasar al siguiente paso.¿Recuerda el campo TTL (Time To Live) que mencionamos anteriormente? Los registros DNS se almacenan en caché durante un período de tiempo, lo cual suele ser muy beneficioso por motivos de rendimiento, porque normalmente no cambian con mucha frecuencia. Cuando sí cambian, hay un período de tiempo (el valor TTL) durante el cual los servidores de caché DNS necesitan que su caché expire antes de comprobar si hay cambios y comportarse en consecuencia.En la mayoría de los casos, es mejor esperar al menos 10 minutos antes de pasar al siguiente y último paso. A veces puede actualizarse un poco más rápido, o puede tardar más. Es raro que esto tarde más de 48 horas.¿Desea comprobar cómo avanza este proceso, conocido como propagación? Puede usar una herramienta de consulta DNS, como WhatsMyDNS. Introduzca su subdominio completo, seleccione CNAME en la lista desplegable y presione el botón Search. Los servidores de caché DNS de todo el mundo responderán para indicarle cuál es su resultado almacenado en caché. Deberá comprobar periódicamente estos resultados hasta que la gran mayoría responda con el valor CNAME asignado.Configurar CDN o su propio servidor de proxy inverso#
Esta sección solo es aplicable si seleccionó la opción Reverse Proxy en el paso anterior.
Configurar AWS CloudFront#
Puede utilizar el servicio CDN proporcionado por proveedores en la nube como AWS CloudFront o Cloudflare Enterprise para configurarlo como su propio servidor de proxy inverso.En el siguiente ejemplo, configuraremos AWS CloudFront como proxy inverso.1.
Inicie sesión en AWS y vaya a CloudFront. Haga clic en Create Distribution. 2.
Configure los ajustes de su distribución. Estos son los valores que deberá cambiar.
| Configuración | Valor |
|---|
| Origin Domain Name | Establecer en {docsSiteId}.apidog.io |
| Name | Una descripción del origen. Este valor le permite distinguir entre múltiples orígenes en la misma distribución y, por lo tanto, debe ser único. |
| Origin Protocol Policy | Establecer en solo HTTP |
| Alternate Domain Names (CNAMEs) | Establecer en su nombre de dominio personalizado (el mismo que configuró en la configuración de Publish durante la configuración del dominio personalizado) |
| SSL Certificate | Establecer en el certificado SSL para su dominio personalizado almacenado en AWS Certificate Manager (ACM). |
3.
Proporcione información en Origin Custom Headers (los campos Header Name y Value aparecen solo después de haber proporcionado un Origin Domain Name)
| Nombre del encabezado | Valor |
|---|
| X-Apidog-Docs-Site-ID | Establecer en {docsSiteId} |
{docsSiteId} es su Docs Site ID, que puede encontrarse en el panel de dominio personalizado. Asegúrese de introducir el ID correcto.4.
Configure los ajustes de Default Cache Behavior. Estos son los valores que deberá cambiar.
| Configuración | Valor |
|---|
| Viewer Protocol Policy | Seleccione Redirect HTTP to HTTPS |
| Allowed HTTP Methods | Seleccione GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE. |
| Cache and origin request settings | Seleccione Use legacy cache settings. Seleccione All para Headers, Query strings y Cookies |
5.
No habilite AWS Web Application Firewall (WAF).
6.
Haga clic en Create distribution en la parte inferior de la página. Verá su distribución recién creada en su lista CloudFront Distributions. Tenga en cuenta que Status mostrará In progress hasta que la distribución esté Deployed.
7.
Añada un nuevo registro CNAME a su DNS para su dominio personalizado que apunte al CloudFront Domain Name de su Distribution. Puede encontrarlo haciendo clic en su Distribution ID, en la pestaña General, Distribution domain name (por ejemplo, fd1fbc7cac6197.cloudfront.net).
Configurar Cloudflare como proxy inverso#
Puede usar Cloudflare Workers para actuar como proxy inverso. Esto le permite mantener su dominio con proxy (Orange Cloud) mientras garantiza que Apidog reciba los identificadores de proyecto necesarios.2.
Haga clic en Create Application y luego en Create Worker. (Continúe con Start with Hello World!, si se le solicita seleccionar un método)
3.
Asigne un nombre a su worker (por ejemplo, apidog-docs-proxy) y haga clic en Deploy.
4.
Haga clic en Edit Code y sustituya el script existente por lo siguiente:
Puede encontrar su {docsSiteId} en el panel de dominio personalizado. Asegúrese de introducir el ID correcto tanto en las variables targetHost como docsSiteId.
5.
Haga clic en Save and Deploy.
6.
Vaya a la pestaña Settings de su Worker, seleccione Domains & Routes y haga clic en el botón +Add.
7.
Introduzca su dominio personalizado (por ejemplo, docs.example.com). Cloudflare gestionará automáticamente los registros DNS y los certificados SSL.
8.
Asegúrese de que el SSL/TLS encryption mode de Cloudflare esté configurado en Full o Full (Strict) para permitir una comunicación segura entre Cloudflare y Apidog.
Antes de adjuntar un dominio personalizado a su worker, asegúrese de que el dominio (por ejemplo, example.com) ya esté añadido a su cuenta de Cloudflare y que sus servidores de nombres estén activos.
Configurar su propio servidor de proxy inverso#
Puede configurar su propio servidor de proxy inverso para la documentación de su API. En el siguiente ejemplo, usaremos Nginx como servidor de proxy inverso.1.
Añada el siguiente contenido al archivo de configuración de Nginx para una configuración sencilla.
:8080 {
handle_path /* {
reverse_proxy http://{docsSiteId}.apidog.io {
header_up X-Apidog-Docs-Site-ID {docsSiteId}
header_up Host "docs.example.com"
}
}
}
{docsSiteId} es su Docs Site ID, que puede encontrarse en el panel de dominio personalizado. Asegúrese de introducir el ID correcto.2.
Configure el registro DNS para que su nombre de dominio personalizado apunte a su servidor de proxy inverso.
Desplegar documentos de API en un subdirectorio de un dominio personalizado#
El Reverse Proxy de Apidog permite desplegar documentos de API en un subdirectorio de un dominio personalizado. Por ejemplo, puede desplegar la documentación en la ruta /api-docs de un dominio como https://example.com. Cuando los usuarios visiten https://example.com/api-docs, accederán a la documentación de API en línea alojada por Apidog.Pasos de configuración:#
1.
En la página de configuración Custom Domain de Apidog, introduzca su dominio personalizado.
2.
Seleccione Reverse Proxy y habilite Use Subdirectory; luego introduzca la ruta del subdirectorio.
3.
A continuación, deberá modificar el archivo de configuración de su servidor web. Suponiendo que esté usando Nginx para aplicar proxy a su servicio, puede consultar la siguiente configuración:
proxy_pass: Reenviar peticiones de clientes a otro servidor (como el servidor de documentación de API de Apidog).
proxy_set_header: Establecer encabezados de petición enviados por el servidor proxy al servidor ascendente, lo que garantiza que la petición se gestione correctamente.
/api-docs/ es el subdirectorio del dominio personalizado y debe terminar con / en la configuración de Nginx.
http://{docsSiteId}.apidog.io/ también debe terminar con /.
Sustituya {docsSiteId} por el ID del sitio de documentación de Apidog. docs.example.com es un dominio personalizado de ejemplo. Sustitúyalo por su dominio personalizado real.
Después de la configuración, debe reiniciar Nginx en su servidor.
Habilitar HTTPS#
La documentación en línea de Apidog admite el protocolo HTTPS, que tiene varias ventajas sobre HTTP:Transmisión segura de datos: HTTPS utiliza cifrado SSL/TLS para garantizar la seguridad de la transmisión de datos, evitando que terceros intercepten información.
Optimización SEO: Los rastreadores de motores de búsqueda prefieren usar HTTPS porque ofrece mejor seguridad y protección de la privacidad. Por lo tanto, los sitios web HTTPS pueden tener mayor autoridad en los rankings de motores de búsqueda que los sitios web HTTP.
Pasos para habilitar HTTPS:#
1.
Vaya a la página Publish y abra la pestaña Custom Domain.
2.
Active HTTPS para habilitar HTTPS y, opcionalmente, puede habilitar Always Use HTTPS para evitar que la comunicación sea secuestrada o ataques de intermediario.
Gestión de certificados SSL#
Una vez que HTTPS esté habilitado, puede elegir cómo gestionar su certificado SSL:Generated by Apidog: Apidog generará automáticamente un certificado SSL.
Use Your Own Certificate: Puede cargar un certificado SSL y una clave privada emitidos por una autoridad certificadora (por ejemplo, Let's Encrypt). Solución de problemas#
Si tiene problemas para configurar su dominio personalizado, póngase en contacto con nosotros a través de Discord.¿Está usando Apidog Europe?#
Si está usando Apidog Europe, asegúrese de estar utilizando el dominio correcto para la configuración de su dominio personalizado.El dominio correcto para Apidog Europe en la configuración anterior es {docsSiteId}.eu.apidog.com. 
