Seguridad de la Documentación API: ¿Está Segura Tu Especificación en Git?

La seguridad de la documentación de la API es una parte del programa de API que casi nadie audita. Proteges la API con autenticación, límites de tasa y pruebas de seguridad, pero la especificación OpenAPI, la página de Swagger UI o el markdown que explica el flujo de autenticación suelen vivir en un repositorio Git o en un host estático que nadie revisa después de configurarlo. El 20 de mayo de 2026, GitHub confirmó que atacantes robaron datos de aproximadamente 3.800 repositorios internos. El punto de entrada fue una extensión de VS Code envenenada instalada en el portátil de un empleado de GitHub. Esa brecha plantea una pregunta práctica: si alguien pudiera modificar silenciosamente tus documentos de API publicados, ¿lo notarías tú y lo notarían tus consumidores?

Prueba Apidog hoy

TL;DR

Una documentación de API segura necesita cuatro propiedades verificables:

• Control de acceso.
• Versionado.
• Integridad.
• Registro de auditoría.

Docs-as-code en Git funciona bien para muchas APIs públicas porque aporta revisión e historial. Se convierte en riesgo cuando el repositorio es público sin control de acceso, cuando la especificación se desincroniza de la API real o cuando un ejemplo manipulado llega a producción sin ser detectado.

Una capa gestionada como Apidog puede añadir protección por contraseña, listas de acceso por IP o correo electrónico, dominios personalizados, control de versiones y una especificación sincronizada con el diseño de la API como fuente de verdad.

Por qué la brecha de GitHub debería hacerte revisar tus documentos de API

El incidente de GitHub no significa que debas abandonar GitHub ni docs-as-code. Sí significa que debes revisar dónde viven tus documentos y quién puede modificarlos.

Según la cobertura de BleepingComputer, el grupo TeamPCP exfiltró repositorios internos de GitHub tras comprometer una extensión de VS Code distribuida desde el marketplace oficial. GitHub indicó que no encontró evidencia de que datos de clientes almacenados fuera de sus repositorios internos se vieran afectados, y la investigación sigue en curso.

El punto importante para equipos de API es este: la documentación no es solo contenido. Es una instrucción operativa.

Cuando un desarrollador se integra con tu API, copia desde tus documentos:

• URLs de endpoints.
• Cabeceras de autenticación.
• Ejemplos de payload.
• Flujos OAuth.
• Snippets de código.
• Especificaciones OpenAPI usadas para generar clientes.

Si un atacante modifica esas instrucciones, no está alterando una página de marketing. Está influyendo en el código que otros ejecutarán en producción. La misma lógica aparece en otras revisiones post-incidente; por ejemplo, nuestro artículo sobre las lecciones de seguridad de API de la brecha de Vercel explica cómo un pequeño cambio en una superficie confiable puede propagarse.

También puedes revisar dos ángulos relacionados:

• Qué significa la brecha de GitHub para las herramientas de API autoalojadas.
• Seguridad de claves de API en extensiones de VS Code.

Qué puede salir mal si tu repositorio o host de documentación se compromete

Piensa en tu documentación como una superficie compuesta por tres partes:

1. El repositorio donde vive la especificación o el markdown.
2. La canalización CI/CD que construye el sitio.
3. El host que sirve los documentos publicados.

Comprometer cualquiera de esas partes puede afectar directamente a tus consumidores.

1. La manipulación de documentación puede llegar a producción

Ejemplo: tu documentación muestra este endpoint:

https://api.payments.acme.com/v2/charge

Un atacante con acceso de escritura lo cambia por un dominio que controla. El sitio sigue cargando. El YAML sigue siendo válido. CI sigue pasando. Pero el siguiente desarrollador que copie el ejemplo enviará tráfico al destino equivocado.

Un fragmento OpenAPI realista podría verse así:

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created

Si alguien cambia solo esta línea:

- url: https://api.acme-pay.com

por un dominio malicioso, cualquier consumidor que regenere su cliente desde esa especificación puede terminar enviando datos sensibles al atacante.

Acción práctica:

• Revisa los cambios de documentación con el mismo rigor que los cambios de código.
• Añade revisiones obligatorias para cambios en servers, security, authorizationUrl, tokenUrl, ejemplos de tokens y snippets de autenticación.
• Genera alertas cuando cambien dominios, endpoints o parámetros sensibles.

2. Puntos finales internos pueden filtrarse

Los repositorios de documentación acumulan contenido con el tiempo:

• Rutas internas.
• Endpoints de administración.
• Operaciones solo para partners.
• Parámetros de debug.
• Ejemplos con estructuras internas.

Si el repositorio se hace público por error o se exfiltra, esos documentos se convierten en un mapa de tu superficie de ataque.

Incluso si la API requiere autenticación, la especificación puede revelar:

• Qué endpoints existen.
• Qué parámetros aceptan.
• Qué IDs o convenciones internas usan.
• Qué flujos de autorización se esperan.

Para revisar este riesgo, usa una lista de comprobación de superficie. Nuestra lista de verificación de pruebas de seguridad de API para 2026 cubre este tipo de revisión.

3. GitHub Pages no ofrece control de acceso real

GitHub Pages sirve archivos estáticos. Para una API completamente pública, eso puede estar bien. Para documentación interna, de clientes o de partners, no es suficiente.

Una URL difícil de adivinar no es control de acceso.

Las URLs se filtran por:

• Historial del navegador.
• Cabeceras Referer.
• Logs de proxy.
• Herramientas de analítica.
• Marcadores compartidos.
• Mensajes internos reenviados.

Acción práctica:

• Si los documentos no son públicos, no los publiques en un host sin autenticación.
• Usa contraseña, allowlist de IP, allowlist de correo, SSO o autenticación personalizada.
• Verifica que puedes revocar acceso a una persona o dominio de forma inmediata.

4. Los documentos obsoletos son difíciles de verificar

No hace falta un atacante para crear riesgo. A veces la documentación simplemente se desincroniza.

Ejemplo común:

1. Se cambia el comportamiento real de un endpoint.
2. Nadie actualiza la especificación.
3. Un consumidor implementa según la documentación.
4. El comportamiento real no coincide.
5. El equipo pierde horas depurando.

Cuando además existe riesgo de manipulación, la pregunta empeora:

¿La documentación está mal porque quedó obsoleta o porque alguien la cambió?

Sin historial verificable y sin una fuente de verdad clara, no puedes responderlo.

Cuándo docs-as-code en Git está bien

Docs-as-code es una práctica válida. Guardar OpenAPI y markdown en Git, construir Swagger UI o Redoc con CI y desplegar en un host estático aporta beneficios reales:

• Pull requests.
• Historial.
• Revisión por pares.
• Versionado junto al código.
• Automatización.

El punto no es “Git sí” o “Git no”. El punto es si esa configuración es adecuada para esa API.

Docs-as-code en Git está bien cuando:

• La API es completamente pública.
• No hay endpoints internos en la especificación publicada.
• El repositorio tiene protección de ramas.
• Los cambios requieren revisiones obligatorias.
• El acceso de escritura está limitado y auditado.
• La pipeline usa acciones fijadas y dependencias revisadas.
• Las credenciales de despliegue tienen alcance mínimo.
• La especificación se valida contra la API real.
• El sitio desplegado puede compararse con la fuente revisada.

Ejemplo de regla mínima en revisión:

Si un PR modifica openapi.yaml, debe revisarlo al menos una persona del equipo de API y una del equipo de seguridad o plataforma.

Cuándo docs-as-code se convierte en riesgo

La misma configuración se vuelve frágil cuando:

• Los documentos deberían ser privados, pero el host no tiene autenticación.
• El acceso de escritura es demasiado amplio.
• Los commits de documentación se aprueban automáticamente.
• La especificación se edita a mano y se desvía de producción.
• El repositorio mezcla endpoints públicos e internos.
• No hay forma de saber si el sitio publicado coincide con el commit revisado.
• Los tokens de CI/CD o cuentas de servicio no se auditan.

La brecha de GitHub encaja con este modelo: el ataque llegó desde un entorno de desarrollador y terminó en repositorios internos. Git aporta transparencia, pero no confidencialidad si el repositorio se exfiltra.

Para una comparación más amplia de alternativas, revisa nuestra comparación de documentos de API autoalojados.

Qué significa realmente “documentación segura de API”

“Documentación segura” no debería ser una frase vaga. Puedes evaluarla con cuatro propiedades.

1. Control de acceso

Pregunta:

¿Quién puede leer estos documentos ahora mismo?

Una configuración segura permite responder y revocar acceso rápido.

Opciones válidas:

• Público para APIs realmente públicas.
• Contraseña para acceso limitado.
• Allowlist de IP para redes concretas.
• Allowlist de correo o dominio.
• SSO o autenticación personalizada.

No válido:

• “Nadie conoce la URL”.
• “No está enlazado desde ninguna parte”.
• “El repositorio es privado, pero el sitio publicado no”.

2. Control de versiones

Pregunta:

¿Puede un consumidor de v1 encontrar todavía la documentación correcta de v1?

Debes poder mantener varias versiones publicadas:

• v1.
• v2.
• beta.
• partner-specific si aplica.

Esto evita que los consumidores antiguos lean accidentalmente documentación de una versión nueva.

3. Integridad

Pregunta:

Si alguien cambia la URL de un endpoint en producción hace una hora, ¿cómo te enteras?

Opciones prácticas:

• Generar documentación desde una fuente de verdad controlada.
• Comparar el sitio desplegado con el commit aprobado.
• Alertar en cambios de dominios, endpoints y flujos de autenticación.
• Bloquear cambios directos en el host publicado.

4. Pista de auditoría

Pregunta:

¿Puedes mostrar quién cambió qué y cuándo durante los últimos 90 días?

Git cubre parte de esto para el repositorio. Pero también necesitas visibilidad sobre:

• Publicaciones.
• Cambios de acceso.
• Cambios de dominio.
• Cambios de versión.
• Cambios en la especificación publicada.

Cómo Apidog ayuda a publicar documentación de API segura

Apidog es una plataforma de API todo en uno para diseñar, depurar, probar, simular y documentar APIs. En el flujo de documentación, ayuda a cubrir las cuatro propiedades anteriores: acceso, versiones, integridad y auditoría.

Para probarlo, descarga Apidog y abre un proyecto con una definición de API.

Publica documentación desde una fuente de verdad controlada

En Apidog, la documentación se genera desde el diseño de la API dentro del proyecto.

Flujo básico:

1. Define endpoints, esquemas y autenticación en el diseñador visual.
2. Revisa la definición de API.
3. Publica la documentación.
4. Comparte el sitio con los consumidores adecuados.

Apidog puede generar automáticamente la documentación a partir de esa definición.

Esto reduce la deriva porque los documentos publicados reflejan el diseño de la API. Para cambiar lo que ven los consumidores, cambias la definición dentro del proyecto, no un archivo suelto en un host estático.

Configura control de acceso real

Al publicar documentación en Apidog, puedes elegir visibilidad y restricciones:

• Público: cualquiera con el enlace puede leerlo. Útil para APIs abiertas.
• Protección por contraseña: compartes una contraseña con las partes interesadas.
• Allowlist de IP: restringes acceso a IPs o rangos concretos, como oficina o VPN.
• Allowlist de correo electrónico: defines correos o dominios permitidos. Por ejemplo: *@suempresa.com.
• Inicio de sesión personalizado: conectas tu propio sistema de autenticación mediante JWT.

Apidog documenta estos métodos en su guía para controlar el acceso a la documentación de API.

Checklist de implementación:

• Publica la documentación como privada si contiene endpoints no públicos.
• Usa allowlist de correo para clientes o partners concretos.
• Usa allowlist de IP para documentación interna.
• Rota contraseñas si un partner deja de necesitar acceso.
• Revisa periódicamente quién sigue teniendo permisos.

Usa un dominio personalizado

Puedes servir la documentación en tu propio dominio, por ejemplo:

developer.tuempresa.com

Apidog admite dominio personalizado mediante CNAME de DNS o proxy inverso.

Un dominio personalizado no es un control de seguridad por sí solo, pero ayuda a centralizar la gobernanza y evita que la documentación quede dispersa en hosts olvidados.

Mantén OpenAPI sincronizado con el diseño de API

La deriva entre especificación y API real es un problema de seguridad porque vuelve la documentación difícil de verificar.

Apidog trata el diseño de API como fuente de verdad y mantiene la documentación sincronizada con ese diseño. También permite importar:

• OpenAPI 3.0.
• OpenAPI 3.1.
• Swagger 2.0.

Si mantienes una especificación a mano en Git, revisa si está realmente sincronizada con producción. Los equipos que vienen de SwaggerHub pueden seguir esta guía para migrar documentos de API de SwaggerHub a Apidog.

Publica múltiples versiones de documentación

Apidog admite control de versiones de documentación. Esto permite mantener varias versiones lado a lado.

Ejemplo:

/docs/v1
/docs/v2
/docs/beta

Así, un consumidor que todavía usa v1 no queda expuesto a documentación de v2 publicada silenciosamente.

Acción práctica:

• Publica una versión por cada versión estable de API.
• No sobrescribas documentación antigua si aún hay consumidores activos.
• Documenta de forma explícita qué versiones están deprecadas.
• Mantén historial de cambios entre versiones.

Comparación de opciones de alojamiento de documentación

Propiedad	Páginas públicas de GitHub (Swagger UI / Redoc)	Documentos autoalojados en su propio servidor	Documentos gestionados (Apidog)
Control de acceso	Ninguno; solo oscuridad de URL	Lo que usted construya y mantenga	Integrado: contraseña, IP, correo electrónico, inicio de sesión personalizado
Control de versiones	Manual; compilaciones o ramas separadas	Manual	Integrado; versiones publicadas lado a lado
Integridad	Revisión de Git + historial, si se aplica	Depende de su pipeline	Documentos generados a partir de un diseño de API controlado
Pista de auditoría	Historial de Git para el repositorio, no para la implementación	Depende de sus registros	Historial de cambios en el diseño y los documentos publicados
Costo de mantenimiento	Bajo de configurar, mantenimiento continuo del pipeline	Alto; usted es dueño de todo el stack	Bajo; la plataforma gestiona el alojamiento y las puertas de acceso
Mejor ajuste	APIs completamente públicas, pipeline disciplinado	Equipos con necesidades estrictas de autoalojamiento	Equipos que necesitan control de acceso sin sobrecarga de operaciones

No hay una opción universalmente correcta.

• Usa GitHub Pages si tu API es completamente pública y tu pipeline está bien protegida.
• Usa autoalojamiento si tienes requisitos estrictos de residencia, aislamiento o infraestructura.
• Usa una capa gestionada si necesitas control de acceso, versiones e integridad sin mantener todo el stack.

Para ampliar la comparación, revisa:

• Comparación de documentos de API autoalojados.
• Comparación de Scalar vs SwaggerHub vs Apidog.

Checklist rápida para auditar tu documentación de API

Usa esta lista en tu siguiente revisión de seguridad:

[ ] ¿Dónde se publica cada documentación de API?
[ ] ¿Qué repositorio o sistema es la fuente de verdad?
[ ] ¿Quién puede leer la documentación?
[ ] ¿Quién puede modificarla?
[ ] ¿Hay protección de ramas o revisión obligatoria?
[ ] ¿La especificación contiene endpoints internos?
[ ] ¿El host publicado requiere autenticación si los documentos no son públicos?
[ ] ¿Puedes revocar acceso en menos de un minuto?
[ ] ¿Puedes ver qué cambió en los últimos 90 días?
[ ] ¿La documentación publicada coincide con la API real?
[ ] ¿Existen versiones separadas para APIs antiguas?
[ ] ¿Se alertan cambios en dominios, endpoints o flujos de auth?

Conclusión

La brecha de GitHub no es una razón para abandonar docs-as-code ni para desconfiar automáticamente de GitHub. Es un aviso para auditar una superficie que muchos equipos ignoran: la documentación de API.

Siguiente paso práctico:

1. Enumera todos los lugares donde publicas documentación de API.
2. Evalúa cada uno con las cuatro propiedades: acceso, versiones, integridad y auditoría.
3. Cierra primero la brecha más crítica.
4. Si el problema principal es control de acceso, publica un proyecto en Apidog con contraseña o allowlist de correo y compáralo con tu flujo actual.