De forma predeterminada, su documentación es accesible en un dominio [subdomain].apidog.io. Sin embargo, puede personalizarlo configurando un dominio personalizado, lo que significa que su audiencia podrá acceder a su documentación en un dominio que se ajuste a su organización.Los dominios personalizados pueden ser configurados por usuarios con permisos de administrador. Siga estos pasos para configurar un dominio personalizado.Iniciar la configuración del dominio personalizado#
Puede acceder a las opciones para configurar un dominio personalizado para un proyecto en el módulo Share del proyecto. Simplemente haga clic en el menú Share Docs en la barra lateral y, a continuación, vaya a la página de configuración Publish en el menú secundario.Verá una sección titulada Custom Domain. Haga clic en el botón Edit para iniciar la configuración del dominio personalizado.Hay dos tipos de opciones para configurar un dominio personalizado:1.
CNAME: Esta es la opción recomendada. Es la más sencilla de configurar y mantener. También es la opción más flexible, ya que le permite configurar un dominio personalizado para un subdominio o un dominio raíz.
2.
Reverse Proxy: Esta opción es más avanzada y requiere que utilice una red de entrega de contenido (CDN) o configure un proxy inverso en su propio servidor. Se recomienda para usuarios que estén familiarizados con estas tecnologías.
Configurar CNAME#
Esto solo se aplica si ha seleccionado 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 lo que debe introducir realmente para configurar el registro pueden diferir entre paneles de control DNS, pero aquí hemos cubierto las opciones más comunes. Si no está seguro, verifíquelo con su proveedor de DNS.El tipo es la clase de registro DNS que desea crear. Aquí, debe elegir CNAME.
El nombre o entrada DNS es donde introduce su subdominio. Es posible que tenga que introducirlo completo (por ejemplo, docs.example.com) o que solo tenga que introducir la parte anterior a su dominio apex (por ejemplo, docs). Si no está seguro de cuál usar, consulte con su proveedor de DNS.
El destino, valor o destination es donde debe apuntar el subdominio. Debería ver el valor correspondiente en la configuración Publish de Apidog cuando elija la opción DNS CNAME. Tendrá un aspecto similar a {projectId}.apidog.io. Debe introducir este valor completo (por ejemplo, 12345678.apidog.io).
También podría ver un campo llamado TTL, que significa Time To Live. Es el número de segundos durante los cuales el registro DNS puede almacenarse en caché. Si no está seguro de qué configurar, le sugerimos seleccionar Auto o mantener el valor predeterminado.
¿Utiliza Cloudflare?#
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é desactivado. Esto es por dos motivos:Esta opción oculta el destino DNS de su dominio al público, lo que impide que Apidog ejecute correctamente comprobaciones rutinarias en su dominio personalizado.
Su dominio personalizado ya se beneficiará de CDN.
Esperar a que los cambios surtan efecto#
La respuesta breve: es posible que tenga que esperar 10 minutes ~ 48 hours para que los cambios DNS surtan efecto antes de pasar al siguiente paso.¿Recuerda el campo TTL (Time To Live) que mencionamos antes? Los registros DNS se almacenan en caché durante un período de tiempo, lo cual suele ser muy beneficioso por motivos de rendimiento, ya que 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 actuar 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, todo podría actualizarse un poco más rápido, o podría tardar más. Es raro que esto tarde más de 48 horas.¿Desea comprobar cómo progresa este proceso, conocido como propagación? Puede utilizar una herramienta de búsqueda DNS, como WhatsMyDNS. Introduzca su subdominio completo, seleccione CNAME en la lista desplegable y pulse 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 proxy inverso#
Esto solo se aplica si ha seleccionado la opción Reverse Proxy en el paso anterior.
Configurar AWS CloudFront como proxy inverso#
Puede utilizar el servicio CDN proporcionado por proveedores en la nube como AWS CloudFront o Cloudflare Enterprise para configurarlo como su propio servidor proxy inverso.En el siguiente ejemplo, configuraremos AWS CloudFront como Reverse Proxy.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 | Configúrelo como {projectId}.apidog.io |
| Name | Una descripción para el origen. Este valor le permite distinguir entre varios orígenes en la misma distribución y, por lo tanto, debe ser único. |
| Origin Protocol Policy | Configúrelo como solo HTTP |
| Alternate Domain Names (CNAMEs) | Configúrelo como su nombre de dominio personalizado (el mismo que configuró en los ajustes Publish durante la configuración del dominio personalizado) |
| SSL Certificate | Configúrelo como 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-Project-ID | Configúrelo como {projectId} |
Puede encontrar el valor projectId en la configuración del proyecto de Apidog.
4.
Configure los ajustes Default Cache Behavior Settings. 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 de CloudFront Distributions. Tenga en cuenta que Status mostrará In progress hasta que la distribución esté Deployed.
7.
Agregue 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 su propio servidor proxy inverso#
Puede configurar su propio servidor proxy inverso para su documentación de API. En el siguiente ejemplo, utilizaremos Nginx como servidor proxy inverso.1.
Agregue el siguiente contenido al archivo de configuración de Nginx para una configuración sencilla.
:8080 {
handle_path /* {
reverse_proxy http://{projectId.apidog.io {
header_up X-Apidog-Project-ID {projectId}
header_up Host "docs.example.com"
}
}
}
}
Puede encontrar el valor {projectId} en la configuración del proyecto de Apidog.
2.
Configure el registro DNS para que su nombre de dominio personalizado apunte a su servidor proxy inverso.
Implementar documentos de API en un subdirectorio de un dominio personalizado#
El Reverse Proxy de Apidog permite implementar documentos de API en un subdirectorio de un dominio personalizado. Por ejemplo, puede implementar la documentación en la ruta /api-docs en 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; a continuación, introduzca la ruta del subdirectorio.
3.
A continuación, deberá modificar el archivo de configuración de su servidor web. Suponiendo que utilice Nginx para aplicar proxy a su servicio, puede consultar la siguiente configuración:
proxy_pass: Reenvía las peticiones del cliente a otro servidor (como el servidor de documentación de API de Apidog).
proxy_set_header: Establece los encabezados de petición enviados por el servidor proxy al servidor ascendente, asegurando 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://{projectId}.apidog.io/ también debe terminar con /.
Sustituya {projectId} por el ID de su proyecto 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, impidiendo que terceros intercepten la información.
Optimización SEO: Los rastreadores de motores de búsqueda prefieren utilizar HTTPS porque ofrece mayor seguridad y protección de la privacidad. Por lo tanto, los sitios web HTTPS pueden tener mayor autoridad en las clasificaciones 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 habilitado HTTPS, 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.¿Utiliza Apidog Europe?#
Si utiliza 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 {projectId}.eu.apidog.com. 
