Skip to main content
La documentación para desarrolladores ayuda a las personas a entender e integrarse con tu producto. Una buena documentación permite que las personas hagan más con tu producto, reduce la carga de soporte, acelera la adopción y mejora la experiencia del desarrollador. Mintlify proporciona infraestructura diseñada para la documentación para desarrolladores.
  • Generación de referencias de API: Genera referencias de API interactivas a partir de especificaciones OpenAPI que permiten a los desarrolladores probar endpoints en tu documentación.
  • Bloques de código con explicaciones: El assistant explica ejemplos de código en contexto, ayudando a los desarrolladores a entender los detalles de implementación.
  • Sincronización con Git: Mantén la documentación sincronizada con tu base de código usando GitHub o GitLab.
  • Control de versiones: Mantén la documentación para múltiples versiones, de modo que los desarrolladores en versiones anteriores aún puedan encontrar información precisa.

​
Requisitos previos

Si aún no has creado un proyecto de Mintlify, consulta la Guía de inicio rápido para desplegar tu sitio.
  • La especificación de tu API en formato OpenAPI (si estás documentando una API)
  • Un repositorio Git para tu documentación
  • Acceso de administrador a tu organización de Mintlify

​
Migra la documentación existente

Si estás creando la documentación desde cero, pasa a Planifica la estructura de la documentación.

​
Audita el contenido existente

Revisa tu documentación actual para entender qué tienes y qué necesitas migrar.
  • Referencia de API: ¿Se genera a partir de una especificación o está escrita a mano? ¿Qué endpoints documentas?
  • Guías y tutoriales: ¿Qué guías de integración tienes? ¿Están actualizadas?
  • Ejemplos de código: ¿Qué lenguajes y frameworks utilizas?
  • Documentación de SDK: ¿Tienes documentación independiente para cada SDK?
  • Cambios: ¿Mantienes un registro de cambios o notas de lanzamiento?
  • Metadata: ¿Tienes metadata para tu contenido, como fechas, autores y etiquetas?

​
Exporta tu contenido existente

  • Exporta a Markdown para la migración más sencilla a Mintlify.
  • Exporta las especificaciones OpenAPI para el contenido de referencia de API.
  • Exporta a HTML si Markdown no está disponible y luego conviértelo a Markdown.

​
Planifica la estructura de tu documentación

La documentación para desarrolladores suele incluir varios tipos de contenido. Estructura la navegación en función de cómo tus usuarios entienden tu producto.
docs.json example
{
  "navigation": {
    "groups": [
      {
        "group": "Get Started",
        "pages": [
          "introduction",
          "quickstart",
          "authentication"
        ]
      },
      {
        "group": "Guides",
        "pages": [
          "guides/webhooks",
          "guides/error-handling",
          "guides/rate-limits",
          "guides/pagination"
        ]
      },
      {
        "group": "Referencia de API",
        "pages": [
          "api-reference/overview",
          "api-reference/users",
          "api-reference/orders",
          "api-reference/products"
        ]
      },
      {
        "group": "SDKs",
        "pages": [
          "sdks/javascript",
          "sdks/python",
          "sdks/go"
        ]
      }
    ]
  }
}
Consulta Navigation para obtener más opciones de configuración.

​
Configura tu referencia de API

Si tienes una API, genera una referencia interactiva a partir de tu especificación OpenAPI.
1

Agrega tu especificación OpenAPI

Agrega el archivo de especificación OpenAPI a tu proyecto. Puedes usar formato YAML o JSON.
your-project/
├── docs.json
├── openapi.yaml
└── api-reference/
    └── overview.mdx
2

Configura la especificación en docs.json

Haz referencia a tu archivo OpenAPI en la configuración de docs.json.
Ejemplo de configuración
{
  "openapi": "openapi.yaml"
}
3

Agrega endpoints a la navigation

Agrega los endpoints a navigation en tu docs.json. Consulta Configuración de OpenAPI para ver las opciones de configuración.
Ejemplo de navegación
{
  "group": "API Reference",
  "pages": [
    "api-reference/overview",
    "api-reference/users/list-users",
    "api-reference/users/get-user",
    "api-reference/users/create-user"
  ]
}

​
Configura el assistant

El assistant ayuda a los desarrolladores a encontrar respuestas y comprender ejemplos de código. Configúralo desde tu dashboard.
  • Preguntas de ejemplo: Añade preguntas dirigidas a desarrolladores como “¿Cómo autentico solicitudes a la API?” o “Muéstrame cómo manejar webhooks”.
  • Explicaciones de código: El assistant puede explicar bloques de código en contexto cuando los desarrolladores hacen preguntas sobre ejemplos específicos.

​
Configurar el versionado

Si mantienes varias versiones de tu API, configura el versionado para que los desarrolladores puedan encontrar la documentación de su versión.
Versioning example
{
  "versions": ["v2", "v1"],
  "navigation": {
    "groups": [
      {
        "group": "Referencia de API",
        "version": "v2",
        "pages": ["v2/api-reference/users"]
      },
      {
        "group": "Referencia de API",
        "version": "v1",
        "pages": ["v1/api-reference/users"]
      }
    ]
  }
}
Para obtener más información, consulta Versiones.

​
Conecta tu repositorio

Instala la Aplicación de GitHub de Mintlify para mantener la documentación sincronizada con tu base de código y permitir contribuciones.
1

Connect your repository

Vincula tu repositorio de GitHub en el dashboard. Esto habilita implementaciones automáticas cuando haces push de cambios.
2

Configure branch settings

Define tu branch de producción y habilita implementaciones de vista previa para las solicitudes de extracción. Esto te permite revisar los cambios en la documentación antes de que se publiquen.
Si usas GitLab, consulta GitLab para obtener instrucciones de configuración.

​
Mantén tu documentación

La documentación para desarrolladores necesita actualizaciones periódicas para que la información sea precisa y útil.
1

Mantén actualizada la referencia de la API

Actualiza tu especificación de OpenAPI cada vez que publiques cambios. Si tu especificación se genera a partir del código, automatiza esto en tu proceso de lanzamiento.
2

Actualiza los ejemplos de código

Revisa los ejemplos de código cuando publiques nuevas versiones del SDK o actualizaciones del producto. Los ejemplos desactualizados provocan errores de integración y solicitudes de soporte.
3

Mantén un registro de cambios

Documenta los cambios incompatibles, las nuevas funcionalidades y las deprecaciones. Los desarrolladores dependen de los registros de cambios para comprender qué cambió entre versiones. Consulta Cambios para obtener más información.
4

Supervisa los comentarios

Revisa las conversaciones del assistant y las métricas de búsqueda para identificar carencias en tu documentación. Si los desarrolladores preguntan repetidamente sobre el mismo tema, mejora esa sección. Consulta Mantenimiento para obtener más información.

​
Próximos pasos

La documentación para desarrolladores está lista para publicarse. Después de desplegarla:
  1. Anuncia la documentación a tu comunidad de desarrolladores.
  2. Supervisa los patrones de búsqueda y las conversaciones en el assistant para identificar brechas.
  3. Configura un proceso para actualizar la documentación con cada nueva versión de la API.
  4. Recopila comentarios de los desarrolladores para mejorar el contenido a lo largo del tiempo.