Guía definitiva: Alojar la documentación de la API en un dominio personalizado

En el competitivo mundo del desarrollo de software, ofrecer una documentación de API clara y accesible es esencial para permitir una integración y adopción perfectas de tus servicios. Una forma eficaz de mejorar la accesibilidad y la profesionalidad de tu documentación de API es alojarla en un dominio personalizado. Esta guía te mostrará los beneficios y los pasos necesarios para configurar tu documentación de API con un dominio personalizado.

Importancia de un dominio personalizado para la documentación de la API

La documentación de la API es un componente fundamental para los desarrolladores que confían en tus API para crear aplicaciones. Alojar esta documentación en un dominio personalizado no solo refuerza la identidad de tu marca, sino que también proporciona una experiencia profesional y fácil de usar para tus usuarios. Al utilizar un dominio personalizado, puedes asegurarte de que tu documentación de API sea fácilmente accesible y refleje la calidad de tu servicio.

Beneficios de alojar la documentación de la API en un dominio personalizado

Coherencia de marca

Un dominio personalizado te permite alinear tu documentación de API con la identidad de tu marca. Crea una experiencia cohesiva para tus usuarios, reforzando la credibilidad y la profesionalidad de tu marca.

Accesibilidad mejorada

El uso de un dominio personalizado hace que tu documentación de API sea más fácil de recordar y acceder. En lugar de una URL genérica o larga, los usuarios pueden navegar rápidamente a un dominio de marca, lo que mejora la experiencia general del usuario.

Seguridad mejorada

Los dominios personalizados a menudo vienen con características de seguridad mejoradas, como certificados SSL, que protegen los datos de tus usuarios y generan confianza en tu servicio. El alojamiento seguro de la documentación garantiza que los usuarios puedan acceder e interactuar de forma segura con tu documentación de API.

Beneficios de SEO

Un dominio personalizado puede mejorar tu posicionamiento en los motores de búsqueda, haciendo que tu documentación sea más fácil de descubrir. Al optimizar tu documentación de API para los motores de búsqueda, puedes atraer a más desarrolladores a tu plataforma.

Pasos para alojar la documentación de la API en un dominio personalizado

Paso 1. Elige una plataforma de alojamiento de documentación

Varias plataformas, como SwaggerHub, Redocly y Apidog, te permiten alojar la documentación de la API. Elige una que se ajuste a tus necesidades y que admita la configuración de un dominio personalizado.

Paso 2. Configura tu dominio personalizado

Una vez que hayas elegido una plataforma, sigue estos pasos generales para configurar tu dominio personalizado:

a. Compra un nombre de dominio: Si aún no tienes un dominio, compra uno a un registrador de dominios como GoDaddy, Namecheap o Google Domains.

b. Configura los ajustes de DNS: Inicia sesión en tu registrador de dominios y navega a la sección de gestión de DNS. Crea un registro CNAME que apunte tu dominio personalizado al dominio de la plataforma de alojamiento de documentación. Por ejemplo, si tu documentación está alojada en docs.yourapi.com, crea un registro CNAME que apunte docs.yourapi.com a yourapi.docs.hostingplatform.com.

c. Verifica la propiedad del dominio: Algunas plataformas requieren que verifiques la propiedad del dominio. Este proceso suele implicar la adición de un registro TXT a tus ajustes de DNS con un código de verificación proporcionado por la plataforma.

d. Configura HTTPS (SSL): Asegúrate de que tu dominio personalizado admita HTTPS para conexiones seguras. Muchas plataformas de alojamiento ofrecen certificados SSL automáticos, pero es posible que tengas que configurarlo manualmente en algunos casos.

Paso 3. Implementa tu documentación de API

Con tu dominio configurado, implementa tu documentación de API en la plataforma de alojamiento. Sigue las instrucciones específicas de la plataforma para cargar tus archivos de documentación o conectar tu repositorio.

Paso 4. Prueba y verifica

Una vez implementada, accede a tu documentación de API a través de tu dominio personalizado para asegurarte de que todo funciona correctamente. Comprueba si hay enlaces rotos, problemas de formato o errores de certificado SSL.

Diseña, autogenera y aloja la documentación de la API utilizando Apidog

En la economía digital, las API (interfaces de programación de aplicaciones) son cruciales para permitir que las aplicaciones de software se comuniquen entre sí. Tanto si eres una startup como una empresa, una documentación de API sólida es esencial para ayudar a los desarrolladores a comprender y utilizar tus API de forma eficiente.

Entre todas las plataformas de alojamiento de documentación de API, Apidog destaca como una plataforma versátil que admite todo el ciclo de vida de la documentación de API, desde el diseño hasta la autogeneración y el alojamiento. Aquí te explicamos por qué debería ser tu herramienta de referencia.

1. Herramienta integral de diseño de API

Apidog proporciona una herramienta de diseño robusta que te permite crear especificaciones de API detalladas. Tanto si empiezas desde cero como si refinas una API existente, la herramienta de diseño de Apidog ofrece:

• Interfaz visual: Una interfaz intuitiva de arrastrar y soltar para diseñar puntos finales de API, esquemas de solicitud/respuesta y modelos de datos.
• Cumplimiento de estándares: Garantiza automáticamente que tus diseños de API cumplan con los estándares de la industria como OpenAPI y Swagger.
• Diseño colaborativo: Permite a los miembros del equipo colaborar en tiempo real, asegurando que tu diseño de API evolucione con la aportación colectiva.

2. Autogenerar documentación

Una de las características destacadas de Apidog es su capacidad para autogenerar documentación de API directamente desde tus especificaciones de API. Esto asegura que tu documentación esté siempre actualizada y sea coherente con el estado actual de tu API.

• Sincronización: Actualiza automáticamente la documentación cada vez que se realizan cambios en el diseño de la API.
• Documentación enriquecida: Incluye descripciones detalladas, modelos de datos, ejemplos de solicitudes y respuestas, y métodos de autenticación.
• Personalización: Te permite añadir notas personalizadas utilizando markdown, ejemplos de código y metadatos para mejorar la documentación.

3. Documentación interactiva de la API

Apidog admite la documentación interactiva, lo que permite a los desarrolladores probar los puntos finales de la API directamente desde la propia documentación. Esta función práctica mejora la experiencia del desarrollador y hace que sea más probable que adopte y utilice tu API:

• Función "Pruébalo": Permite a los desarrolladores ejecutar solicitudes de API y ver las respuestas directamente dentro de la documentación en línea.
• Gestión de la autenticación: Gestiona las claves de API, los tokens y otros métodos de autenticación sin problemas.

4. Alojamiento fácil y dominios personalizados

Apidog no solo te ayuda a diseñar y generar documentación, sino que también ofrece soluciones de alojamiento robustas. Puedes alojar tu documentación en un dominio personalizado, mejorando la profesionalidad de tu marca y centralizando tus recursos.

• Dominios personalizados: Aloja tu documentación en un dominio que se alinee con tu marca (por ejemplo, docs.tuempresa.com).
• Seguridad: Proporciona cifrado SSL, autenticación de usuarios y gestión de permisos para mantener tu documentación segura.

5. Integración perfecta con las herramientas de desarrollo

Apidog se integra perfectamente con varias herramientas de desarrollo y CI/CD para agilizar tu flujo de trabajo. Esta compatibilidad asegura que tu documentación forme parte de tu ciclo de vida de desarrollo más amplio:

• Sistemas de control de versiones: Se integra con GitHub, GitLab y Bitbucket.
• Pipelines de CI/CD: Compatible con Jenkins, CircleCI y otras herramientas de CI/CD.

6. Funciones de colaboración robustas

Para los equipos, la colaboración es clave para mantener una documentación precisa y completa. Apidog admite múltiples colaboradores y proporciona funciones para asegurar que los cambios se rastrean y gestionan de forma eficiente:

• Edición en tiempo real: Varios miembros del equipo pueden trabajar en la documentación simultáneamente.
• Control de versiones: Rastrea los cambios, revierte a versiones anteriores y gestiona las actualizaciones de la documentación sin problemas.

Configuración de dominios personalizados para documentos de API

Apidog ofrece la posibilidad de utilizar un dominio personalizado para tu documentación de API. Aquí tienes una guía paso a paso sobre cómo puedes hacerlo:

Paso 1. Iniciar la configuración del dominio personalizado

Los dominios personalizados pueden ser configurados por usuarios con acceso de propietario o administrador. Sigue estos pasos para empezar:

1. Acceder al módulo de compartir

Navega al módulo de compartir del proyecto en Apidog.

• Haz clic en el menú Compartir documentos en la barra lateral.
• Ve a la página de ajustes de Publicar en el menú secundario.

2. Iniciar la configuración del dominio personalizado

• En la sección Dominio personalizado, haz clic en el botón Editar.

Verás dos opciones para configurar un dominio personalizado:

• CNAME: Recomendado por su simplicidad y flexibilidad.
• Proxy inverso: Más avanzado, adecuado para usuarios familiarizados con la configuración de CDN o proxy inverso.

Paso 2. Configurar el dominio personalizado para los documentos de la API

Método 1: Configurar el dominio personalizado utilizando CNAME

1. Configurar un registro CNAME

La configuración de DNS se realiza en el panel de control de tu proveedor de DNS. Aquí tienes un recorrido genérico:

• Tipo: Elige CNAME.
• Nombre o entrada DNS: Introduce tu subdominio (por ejemplo, docs.example.com o simplemente docs si el dominio está implícito).
• Destino o valor o destino: Aquí es donde debe apuntar el subdominio, que se puede encontrar en los ajustes de publicación de Apidog cuando eliges la opción CNAME. Se verá algo así: {projectId}.apidog.io (por ejemplo, 12345678.apidog.io).
• TTL (Time To Live): Establece en Auto o deja el valor predeterminado si no estás seguro.

Asegúrate de que no existan registros en conflicto (como A, AAAA, TXT) para el subdominio elegido. Elimina estos si es necesario antes de añadir tu registro CNAME.

Nota especial para usuarios de Cloudflare:

Si utilizas Cloudflare:

• Asegúrate de que el proxy de Cloudflare esté desactivado.
• Esto evita la ofuscación del destino DNS y permite a Apidog realizar comprobaciones rutinarias del dominio.

2. Esperar la propagación del DNS

Los cambios de DNS suelen tardar entre 10 minutos y 48 horas en propagarse. Para rastrear el progreso, puedes utilizar una herramienta de búsqueda de DNS como WhatsMyDNS. Introduce tu subdominio, elige CNAME y pulsa buscar para ver las actualizaciones de propagación en tiempo real.

Método 2: Configurar el dominio personalizado utilizando un servidor web

Este paso es relevante si eliges la opción Proxy inverso.

Para los usuarios que configuran su servidor proxy inverso, aquí te explicamos cómo configurar Nginx:

1. Configuración de Nginx:

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

Ejemplo de configuración de Caddy:

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

      }
}
}

2. Configurar el registro DNS:

Configura el registro DNS para que tu nombre de dominio personalizado apunte a tu servidor proxy inverso.

Método 3: Configurar el dominio personalizado utilizando una CDN

Este paso es relevante si eliges la opción Proxy inverso.

1. Configurar AWS CloudFront como proxy inverso

Puedes utilizar AWS CloudFront u otros servicios de CDN como tu servidor proxy inverso. Utilizaremos AWS CloudFront como servidor proxy inverso en este ejemplo.

Inicia sesión en AWS y navega a CloudFront. Haz clic en Crear distribución.

Configura los ajustes de distribución:

• Nombre de dominio de origen: {projectId}.apidog.io
• Nombre: Una descripción para el origen, que debe ser única, te permite diferenciar entre múltiples orígenes dentro de la misma distribución.
• Política de protocolo de origen: Establece en HTTP solamente.
• Nombres de dominio alternativos (CNAME): Tu nombre de dominio personalizado.
• Certificado SSL: Elige el certificado SSL de AWS Certificate Manager (ACM).

Encabezados personalizados de origen:

• Nombre del encabezado: X-Apidog-Project-ID
• Valor: {projectId}

Ajustes de comportamiento de caché predeterminados:

• Política de protocolo de visualización: Redirigir HTTP a HTTPS
• Métodos HTTP permitidos: Selecciona GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
• Ajustes de solicitud de caché y origen: Utiliza los ajustes de caché heredados, seleccionando Todo para Encabezados, Cadenas de consulta y Cookies.

2. Terminar de crear la distribución:

Haz clic en Crear distribución en la parte inferior de la página. El estado de la distribución se mostrará como "En curso" hasta que se implemente.

3. Configuración de DNS:

Añade un registro CNAME en el panel de control de tu proveedor de DNS apuntando a tu nombre de dominio de CloudFront.

Integrar el documento de API en el subdirectorio de tu sitio web

Disponible en la versión Apidog ≥ 2.5.24. Puedes integrar la documentación de la API en un subdirectorio (por ejemplo, Tu-Sitio-Web.com/api-docs).

1. Activar el proxy inverso en Apidog:

• Ve a los ajustes de Dominio personalizado.
• Haz clic en Proxy inverso y activa Utilizar subdirectorio.

2. Modificar la configuración del servidor web (por ejemplo, Nginx):

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

Buenas prácticas para la documentación de la API

• Marca coherente: Asegúrate de que tu dominio personalizado y el contenido de tu documentación de API se alineen con el estilo y los mensajes de tu marca.
• Sé exhaustivo: Incluye explicaciones detalladas, ejemplos de código y casos de uso.
• Proporciona una navegación clara: Asegúrate de que tu documentación sea fácil de navegar con una estructura clara y funcionalidad de búsqueda.
• Actualizaciones periódicas: Mantén tu documentación actualizada con los últimos cambios y mejoras de la API.
• Supervisión: Supervisa regularmente tu dominio personalizado para detectar cualquier problema o tiempo de inactividad para mantener una experiencia de usuario perfecta.
• Comentarios de los usuarios: Anima a los usuarios a proporcionar comentarios sobre tu documentación para mejorar continuamente su claridad y usabilidad.

Conclusión

En el campo altamente competitivo del desarrollo de software, proporcionar una documentación de API clara y accesible es crucial para la integración y adopción perfectas de tus servicios. Alojar tu documentación de API en un dominio personalizado ofrece numerosos beneficios, incluyendo una mayor coherencia de marca, una mejor accesibilidad, una mayor seguridad y un mejor rendimiento de SEO. Siguiendo los pasos descritos en esta guía, puedes configurar e implementar fácilmente tu documentación de API en un dominio personalizado, mejorando así la experiencia del usuario y reforzando la profesionalidad de tu marca.

Plataformas como Apidog hacen que este proceso sea aún más sencillo al ofrecer herramientas integrales para diseñar, autogenerar y alojar la documentación de la API. Con características como una interfaz de diseño robusta, documentación interactiva, integración perfecta con herramientas de desarrollo y sólidas capacidades de colaboración, Apidog destaca como una solución versátil para gestionar tus necesidades de documentación de API.

En última instancia, invertir en un dominio personalizado para tu documentación de API no solo eleva la percepción de tu servicio, sino que también asegura que los desarrolladores puedan acceder y utilizar tus API de forma eficiente. Al priorizar la documentación de calidad y aprovechar herramientas como Apidog, puedes fomentar una mayor confianza y compromiso con tu comunidad de desarrolladores, impulsando el éxito y la adopción de tus API.