Configuración de OpenAPI

OpenAPI es una especificación para describir APIs. Mintlify es compatible con documentos OpenAPI 3.0 y 3.1 para generar documentación de API interactiva y mantenerla actualizada.

Agrega un archivo de especificación OpenAPI

Para documentar tus endpoints con OpenAPI, necesitas una o más especificaciones OpenAPI válidas en formato JSON o YAML que sigan la especificación OpenAPI 3.0 o 3.1. Agrega especificaciones OpenAPI a tu repositorio de documentación o alójalas en línea donde puedas acceder a ellas mediante una URL. Las especificaciones almacenadas en tu repositorio se sirven como archivos descargables en la ruta correspondiente de tu dominio de documentación. Por ejemplo, https://your-domain/docs/openapi.json. Haz referencia a cualquier número de especificaciones OpenAPI en el elemento de navigation de tu docs.json para crear páginas para los endpoints de tu API. Cada archivo de especificación genera su propio conjunto de endpoints.

"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "openapi": "openapi.json"
    }
  ]
}

Mintlify admite $ref para referencias internas únicamente dentro de un solo documento OpenAPI. No se admiten referencias externas.

Describe tu API

Recomendamos los siguientes recursos para aprender y elaborar tu especificación de OpenAPI.

Guía de OpenAPI de Swagger para aprender la sintaxis de OpenAPI.
Fuentes Markdown de la especificación OpenAPI para consultar los detalles de la versión más reciente de la especificación.
Swagger Editor para editar, validar y depurar tu documento de OpenAPI.
La CLI de Mint para validar tu documento de OpenAPI con el comando: mint validate.

La Guía de OpenAPI de Swagger corresponde a OpenAPI v3.0, pero casi toda la información es aplicable a v3.1. Para obtener más información sobre las diferencias entre v3.0 y v3.1, consulta Migrating from OpenAPI 3.0 to 3.1.0 en el blog de OpenAPI.

Especifica la URL base de tu API

Para habilitar el área de pruebas de la API, añade un campo servers a tu especificación de OpenAPI con la URL base de tu API.

{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}

En una especificación de OpenAPI, los distintos endpoints de la API se definen por sus rutas, como /users/{id} o simplemente /. La URL base indica dónde se deben anexar esas rutas. Para obtener más información sobre cómo configurar el campo servers, consulta API Server and Base Path en la documentación de OpenAPI. El área de pruebas de la API usa estas URL de servidor para determinar adónde enviar las solicitudes. Si especificas varios servidores, un menú desplegable permite a los usuarios alternar entre ellos. Si no especificas un servidor, el área de pruebas de la API utiliza el modo simple, ya que no puede enviar solicitudes sin una URL base. Si tu API tiene endpoints que se encuentran en distintas URL, puedes sobrescribir el campo servers para una ruta u operación determinada.

Especificar la autenticación

Para habilitar la autenticación en la documentación y el playground de tu API, configura los campos securitySchemes y security en tu especificación de OpenAPI. Las descripciones de la API y el playground de la API agregan campos de autenticación basados en la configuración de seguridad de tu especificación de OpenAPI.

Define tu método de autenticación.

Agrega el campo securitySchemes para definir cómo se autentican los usuarios.Este ejemplo muestra una configuración de autenticación Bearer.

{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}

Aplica la autenticación a tus endpoints.

Agrega el campo security para requerir autenticación.

{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}

Los tipos de autenticación más comunes incluyen:

Claves de API: Para claves en encabezado, consulta o cookie.
Bearer: Para tokens JWT u OAuth.
Básica: Para usuario y contraseña.

Si distintos endpoints de tu API requieren diferentes métodos de autenticación, puedes anular el campo security para una operación determinada. Para obtener más información sobre cómo definir y aplicar la autenticación, consulta Authentication en la documentación de OpenAPI.

Establecer valores predeterminados para esquemas de seguridad

Usa la extensión x-default en un esquema de seguridad para rellenar previamente el campo de autenticación en el playground de la API. Esto es útil para proporcionar valores de ejemplo o credenciales de prueba que ayuden a los usuarios a comenzar rápidamente.

{
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "x-default": "your-api-key-here"
      }
    }
  }
}

La extensión x-default admite los tipos de esquema de seguridad apiKey y http bearer. El valor aparece como la entrada predeterminada en los campos de autenticación del playground. También puedes usar x-default en cualquier propiedad de esquema en tu especificación de OpenAPI para establecer un valor predeterminado en el playground de la API sin afectar el campo default en la definición del esquema.

Personaliza las páginas de tus endpoints

Personaliza las páginas de tus endpoints añadiendo la extensión x-mint a tu especificación de OpenAPI. La extensión x-mint te ofrece un control adicional sobre cómo tu documentación de API se genera y se presenta.

Metadatos

Sobrescribe los metadatos predeterminados de las páginas de API generadas añadiendo x-mint: metadata a cualquier operación. Puedes usar cualquier campo de metadatos válido en el frontmatter de MDX, excepto openapi.

{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "description": "Retrieve a list of users",
        "x-mint": {
          "metadata": {
            "title": "List all users",
            "sidebarTitle": "List users",
            "description": "Obtener datos de usuarios paginados con opciones de filtrado",
            "og:title": "Display a list of users"
          }
        },
        "parameters": [
          {
            // Parameter configuration
          }
        ]
      }
    }
  }
}

También puedes controlar cómo se muestra el playground para cada endpoint usando los campos de metadata playground y groups:

{
  "paths": {
    "/admin/users": {
      "post": {
        "summary": "Crear usuario administrador",
        "x-mint": {
          "metadata": {
            "playground": "auth",
            "groups": ["admin"],
            "public": true
          }
        }
      }
    }
  }
}

Esta configuración hace que la página sea pública mientras restringe el playground interactivo a usuarios autenticados del grupo admin.

Contenido

Agrega contenido antes de la documentación de la API generada automáticamente usando x-mint: content. La extensión x-mint: content es compatible con todos los componentes y el formato MDX de Mintlify.

{
  "paths": {
    "/users": {
      "post": {
        "summary": "Crear usuario",
        "x-mint": {
          "content": "## Requisitos previos\n\nEste endpoint requiere privilegios de administrador y tiene límite de tasa.\n\n<Note>Los correos electrónicos de los usuarios deben ser únicos en todo el sistema.</Note>"
        },
        "parameters": [
          {
            // Configuración de parámetros
          }
        ]
      }
    }
  }
}

href

Establece la URL de la página del endpoint generada automáticamente usando x-mint: href. Cuando x-mint: href está presente, la página de la API generada utiliza la URL especificada en lugar de la URL predeterminada generada automáticamente.

{
  "paths": {
    "/legacy-endpoint": {
      "get": {
        "summary": "Endpoint heredado",
        "x-mint": {
          "href": "/deprecated-endpoints/legacy-endpoint"
        }
      }
    },
    "/documented-elsewhere": {
      "post": {
        "summary": "Endpoint especial",
        "x-mint": {
          "href": "/guides/special-endpoint-guide"
        }
      }
    }
  }
}

Píldoras de parámetro

Anota los parámetros en la referencia de la API y en el playground con etiquetas de píldora personalizadas usando x-mint.pre y x-mint.post en cualquier esquema. Las píldoras pre se renderizan antes del nombre del parámetro y las píldoras post se renderizan después, junto con las píldoras integradas de Mintlify como required, read-only y write-only. Ambos campos aceptan un arreglo de cadenas. Cada cadena se convierte en su propia píldora.

{
  "components": {
    "schemas": {
      "User": {
        "properties": {
          "email": {
            "type": "string",
            "x-mint": {
              "pre": ["PII"],
              "post": ["indexed", "unique"]
            }
          }
        }
      }
    }
  }
}

Para mostrar campos arbitrarios de la especificación OpenAPI como píldoras en cada parámetro sin editar cada esquema, configura api.params.post en tu docs.json. Enumera las claves de los campos que quieres mostrar y Mintlify lee cada valor del esquema y renderiza las píldoras correspondientes automáticamente.

{
  "api": {
    "params": {
      "post": ["nullable", "x-internal"]
    }
  }
}

Con esta configuración, una propiedad como { "type": "string", "nullable": true, "x-internal": "admin" } renderiza las píldoras nullable y admin junto a su nombre. Las píldoras post aparecen en este orden: píldoras integradas (read-only, write-only), luego las píldoras impulsadas por la configuración api.params.post y, por último, las píldoras x-mint.post por propiedad.

Nombres de visualización de grupo

Establece un nombre de visualización personalizado para el grupo de navegación de un tag usando la extensión x-group en un objeto de tag. De forma predeterminada, Mintlify usa el name del tag tanto como etiqueta del grupo de navegación como segmento de la ruta URL. La extensión x-group sobrescribe la etiqueta del grupo mientras mantiene el nombre del tag para la URL. Esto es útil cuando deseas un nombre de grupo legible que difiera del tag usado en las rutas de tu API.

{
  "tags": [
    {
      "name": "user-management",
      "description": "Endpoints for managing users",
      "x-group": "User Management"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "tags": ["user-management"],
        "summary": "List users"
      }
    }
  }
}

En este ejemplo, el grupo de navegación se muestra como “User Management”, pero la URL de la página generada sigue usando el nombre del tag user-management como segmento de la ruta.

Generar automáticamente páginas de API

Añade un campo openapi a cualquier elemento de navegación en tu docs.json para generar automáticamente páginas para endpoints de OpenAPI. Puedes controlar dónde aparecen estas páginas en tu estructura de navegación, ya sea como secciones de API dedicadas o junto con otras páginas. El campo openapi acepta una ruta en tu repositorio de documentación o una URL a un documento OpenAPI alojado.

Cuando usas una URL para tu especificación OpenAPI, los cambios en la especificación no generan un push a Git, por lo que tus docs no se redespliegan automáticamente. Para mantener tus docs sincronizados, llama al endpoint de API Trigger deployment en la misma acción de CI que genera o actualiza tu especificación. De esta forma, tus docs se actualizan automáticamente sin necesidad de activar manualmente un despliegue desde el dashboard.

Las páginas de endpoints generadas tienen estos metadatos predeterminados:

title: El campo summary de la operación, si está presente. Si no hay summary, Mintlify genera el título a partir del método HTTP y el endpoint.
description: El campo description de la operación, si está presente.
version: El valor version del ancla o pestaña principal, si está presente.
deprecated: El campo deprecated de la operación. Si es true, aparece una etiqueta de “deprecated” junto al título del endpoint en la navegación lateral y en la página del endpoint.

Para excluir endpoints específicos de tus páginas de API generadas automáticamente, añade la propiedad x-hidden a la operación en tu especificación de OpenAPI.

Hay dos enfoques para añadir páginas de endpoints a tu documentación:

Secciones de API dedicadas: Referencia especificaciones de OpenAPI en elementos de navegación para crear secciones de API dedicadas.
Endpoints selectivos: Referencia endpoints específicos en tu navegación junto con otras páginas.

Secciones de API dedicadas

Crea secciones de API dedicadas añadiendo un campo openapi a un elemento de navegación y ninguna otra página. Todos los endpoints de la especificación aparecen en la sección generada.

"navigation": {
  "tabs": [
    {
        "tab": "Referencia de API",
        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}

Para organizar varias especificaciones de OpenAPI en secciones separadas de tu documentación, asigna cada especificación a un grupo distinto dentro de la jerarquía de navegación. Cada grupo puede referenciar su propia especificación de OpenAPI.

"navigation": {
  "tabs": [
    {
      "tab": "Referencia de API",
      "groups": [
        {
          "group": "API de Usuarios",
          "openapi": {
            "source": "/path/to/users-openapi.json",
            "directory": "users-api-reference"
          }
        },
        {
          "group": "API de Administrador",
          "openapi": {
            "source": "/path/to/admin-openapi.json",
            "directory": "admin-api-reference"
          }
        }
      ]
    }
  ]
}

El campo directory es opcional y especifica dónde Mintlify almacena las páginas de API generadas en tu repositorio de documentación. Si no se especifica, de forma predeterminada se usa el directorio api-reference de tu repositorio.

Endpoints selectivos

Cuando quieras tener más control sobre dónde aparecen los endpoints en tu documentación, puedes hacer referencia a endpoints específicos en la navegación. Este enfoque te permite generar páginas de endpoints de API junto con otros contenidos. También puedes usarlo para combinar endpoints de diferentes especificaciones de OpenAPI.

Establecer una especificación de OpenAPI predeterminada

Configura una especificación de OpenAPI predeterminada para un elemento de navegación. Luego, referencia endpoints específicos en el campo pages.

"navigation": {
  "tabs": [
    {
      "tab": "Primeros pasos",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "Referencia de API",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "api-overview",
        "GET /users",
        "POST /users",
        "guides/authentication"
      ]
    }
  ]
}

Cualquier entrada de página que coincida con el formato METHOD /path genera una página de API para ese endpoint utilizando la especificación predeterminada de OpenAPI.

Herencia de especificaciones de OpenAPI

Los elementos de navegación secundarios heredan la especificación de OpenAPI de su elemento principal, a menos que definan la suya propia.

{
  "group": "Referencia de API",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "overview",
    "authentication",
    "GET /users",
    "POST /users",
    {
      "group": "Pedidos",
      "openapi": "/path/to/openapi-v2.json",
      "pages": [
        "GET /orders",
        "POST /orders"
      ]
    }
  ]
}

Endpoints individuales

Haz referencia a endpoints específicos sin establecer una especificación de OpenAPI predeterminada, incluyendo la ruta del archivo. Puedes referenciar endpoints de múltiples especificaciones de OpenAPI en la misma sección de la documentación.

"navigation": {
  "pages": [
    "introduccion",
    "guias-de-usuario",
    "/path/to/users-openapi.json POST /users",
    "/path/to/orders-openapi.json GET /orders"
  ]
}

Este enfoque es útil cuando necesitas endpoints individuales de distintas especificaciones, solo quieres incluir algunos endpoints o prefieres incluir endpoints junto con otros tipos de documentación.

Crea páginas MDX a partir de tu especificación de OpenAPI

Para tener un control más granular de las páginas de endpoints individuales, crea páginas MDX a partir de tu especificación de OpenAPI. Esto te permite personalizar los metadatos y el contenido de la página, además de reordenar o excluir páginas en la navegación, mientras sigues utilizando los parámetros y respuestas generados automáticamente. Hay dos formas de documentar tu especificación de OpenAPI con páginas MDX individuales:

Documenta los endpoints con el campo openapi en el frontmatter.
Documenta los modelos de datos con el campo openapi-schema en el frontmatter.

Document endpoints

Crea una página para cada endpoint y especifica qué operación de OpenAPI mostrar usando el campo openapi en el frontmatter.

---
title: "Obtener usuarios"
description: "Devuelve todas las plantas del sistema a las que el usuario tiene acceso"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---

El método y la ruta deben coincidir exactamente con tu especificación de OpenAPI. Si tienes varias especificaciones de OpenAPI, incluye la ruta a la especificación correcta en tu referencia. También puedes hacer referencia a URLs externas de OpenAPI en docs.json.

Generar automáticamente páginas de endpoints

Para generar automáticamente archivos MDX a partir de tu especificación de OpenAPI, usa el scraper de Mintlify.

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o <folder-name>

Agrega la opción -o para especificar una carpeta donde se crearán los archivos. Si no se especifica una carpeta, los archivos se crean en el directorio de trabajo.

Documentar modelos de datos

Crea una página para cada estructura de datos definida en components.schemas de tu especificación de OpenAPI usando el campo openapi-schema en el frontmatter.

---
openapi-schema: OrderItem
---

Si tienes esquemas con el mismo nombre en varios archivos, especifica el archivo de OpenAPI:

---
openapi-schema: en-schema.json OrderItem
---

Webhooks

Los webhooks son devoluciones de llamada (callbacks) HTTP que tu API envía para notificar a sistemas externos cuando se producen eventos. Los documentos de OpenAPI 3.1+ admiten webhooks. Agrega un campo webhooks a tu documento de OpenAPI junto con el campo paths. Para obtener más información sobre cómo definir webhooks, consulta Webhooks en la documentación de OpenAPI. Para crear una página MDX para un webhook (OpenAPI 3.1+), usa webhook en lugar de un método HTTP:

---
title: "Webhook de pedido actualizado"
description: "Se activa cuando se actualiza un pedido"
openapi: "openapi.json webhook orderUpdated"
---

El nombre del webhook debe coincidir exactamente con la clave en el campo webhooks de tu especificación de OpenAPI.

Primeros pasos

Organizar

Personalizar

Crear contenido

Documentar APIs

Desplegar

Optimizar

Configuración de OpenAPI

Agrega un archivo de especificación OpenAPI

Describe tu API

Especifica la URL base de tu API

Especificar la autenticación

Establecer valores predeterminados para esquemas de seguridad

Personaliza las páginas de tus endpoints

Metadatos

Contenido

href

Píldoras de parámetro

Nombres de visualización de grupo

Generar automáticamente páginas de API

Secciones de API dedicadas

Endpoints selectivos

Establecer una especificación de OpenAPI predeterminada

Herencia de especificaciones de OpenAPI

Endpoints individuales

Crea páginas MDX a partir de tu especificación de OpenAPI

Document endpoints

Generar automáticamente páginas de endpoints

Documentar modelos de datos

Webhooks

Primeros pasos

Organizar

Personalizar

Crear contenido

Documentar APIs

Desplegar

Optimizar

Documentation Index

​Agrega un archivo de especificación OpenAPI

​Describe tu API

​Especifica la URL base de tu API

​Especificar la autenticación

​Establecer valores predeterminados para esquemas de seguridad

​Personaliza las páginas de tus endpoints

​Metadatos

​Contenido

​href

​Píldoras de parámetro

​Nombres de visualización de grupo

​Generar automáticamente páginas de API

​Secciones de API dedicadas

​Endpoints selectivos

​Establecer una especificación de OpenAPI predeterminada

​Herencia de especificaciones de OpenAPI

​Endpoints individuales

​Crea páginas MDX a partir de tu especificación de OpenAPI

​Document endpoints

​Generar automáticamente páginas de endpoints

​Documentar modelos de datos

​Webhooks

Agrega un archivo de especificación OpenAPI

Describe tu API

Especifica la URL base de tu API

Especificar la autenticación

Establecer valores predeterminados para esquemas de seguridad

Personaliza las páginas de tus endpoints

Metadatos

Contenido

href

Píldoras de parámetro

Nombres de visualización de grupo

Generar automáticamente páginas de API

Secciones de API dedicadas

Endpoints selectivos

Establecer una especificación de OpenAPI predeterminada

Herencia de especificaciones de OpenAPI

Endpoints individuales

Crea páginas MDX a partir de tu especificación de OpenAPI

Document endpoints

Generar automáticamente páginas de endpoints

Documentar modelos de datos

Webhooks