Configuración de la API

Usa el campo api en docs.json para configurar qué especificaciones de API generan páginas de API, el área de pruebas interactiva de la API para probar endpoints, y cómo generar y mostrar ejemplos de código.

Ajustes

`api`

Tipo: object Define todos los ajustes relacionados con la API bajo la clave api.

string or array or object

Archivos de especificación OpenAPI para generar páginas de referencia de API. Acepta una única ruta o URL, un array de rutas, URLs y objetos, o un objeto que especifica una fuente, un directorio y overlays.

Mostrar api.openapi object

string

URL o ruta a tu archivo de especificación OpenAPI. Longitud mínima: 1.

string

Directorio donde buscar archivos OpenAPI. No incluyas una barra inicial.

array of string

Rutas o URLs de documentos de OpenAPI Overlay que se aplican a la especificación, en orden. Un array vacío deshabilita todos los overlays de la especificación, incluidos los descubiertos automáticamente.

"openapi": "openapi.json"

"openapi": [
  "openapi/v1.json",
  "openapi/v2.json",
  "https://api.example.com/openapi.yaml"
]

"openapi": {
  "source": "openapi.json",
  "directory": "api-reference"
}

"openapi": {
  "source": "openapi.json",
  "overlays": ["overlays/docs-adjustments.yaml"]
}

string or array or object

Archivos de especificación AsyncAPI para generar páginas de referencia de API basadas en eventos. Acepta una única ruta o URL, un array de rutas y URLs, o un objeto que especifica una fuente y directorio.

Mostrar api.asyncapi object

string

URL o ruta a tu archivo de especificación AsyncAPI. Longitud mínima: 1.

string

Directorio donde buscar archivos AsyncAPI. No incluyas una barra inicial.

"asyncapi": "asyncapi.json"

"asyncapi": [
  "asyncapi/events.yaml",
  "asyncapi/webhooks.yaml"
]

"asyncapi": {
  "source": "asyncapi.json",
  "directory": "websockets"
}

object

Configuración del área de pruebas interactiva de la API.

Mostrar api.playground

"interactive" | "simple" | "none" | "auth"

El modo de visualización del área de pruebas. El valor predeterminado es interactive.

interactive: Área de pruebas interactiva completa con constructor de solicitudes
simple: Vista simplificada sin el constructor de solicitudes
none: Ocultar el área de pruebas por completo
auth: Mostrar el área de pruebas solo a usuarios autenticados

boolean

Si se deben enrutar las solicitudes de API a través de un servidor proxy. El valor predeterminado es true.

boolean

Indica si se deben incluir cookies y encabezados de autenticación en las solicitudes cross-origin cuando proxy es false. El valor predeterminado es false. No tiene efecto cuando proxy es true.

object

Configuración de visualización para los parámetros de la API.

Mostrar api.params

"all" | "closed"

Si se expanden todos los parámetros de forma predeterminada. El valor predeterminado es closed.

array of string

Claves de campos de la especificación OpenAPI que se mostrarán como píldoras post junto al nombre de cada parámetro en las páginas de referencia de la API y en el playground. Para cada clave que enumeres, Mintlify lee el valor del esquema y lo renderiza como una píldora:

Los valores de cadena se renderizan como la cadena literal.
true renderiza el nombre de la clave como etiqueta de la píldora. false, null y las cadenas vacías no renderizan nada.
Los valores numéricos renderizan el número convertido a cadena.
Los arreglos de cadenas o números renderizan una píldora por elemento.
Los objetos y otros valores se omiten.

Usa esto para exponer campos personalizados de OpenAPI, como x-internal, nullable o extensiones de proveedor, como anotaciones visuales en cada parámetro sin necesidad de configuración por propiedad.

"collapsed" | "expanded" | "static"

Cómo se muestran los campos opcionales de la solicitud en el playground de la API. Los campos obligatorios siempre aparecen primero. El valor predeterminado es collapsed.

collapsed: Oculta los campos opcionales detrás de un control para expandir en cada sección.
expanded: Muestra los campos opcionales de forma predeterminada. Los lectores aún pueden contraerlos.
static: Muestra siempre los campos opcionales después de los obligatorios, sin controles para expandir o contraer.

"full"

Modo de visualización de la URL base en el encabezado del endpoint. Establece full para mostrar siempre la URL base completa en cada página de endpoint. Por defecto, la URL base solo se muestra cuando hay múltiples URLs base para seleccionar.

object

Configuración para los ejemplos de código de API generados automáticamente.

Mostrar api.examples

array of string

Lenguajes para los fragmentos de código generados automáticamente. Consulta lenguajes compatibles para ver la lista completa de lenguajes y alias disponibles.

"required" | "all"

Si se incluyen parámetros opcionales en los ejemplos generados. El valor predeterminado es all.

boolean

Si se precarga el área de pruebas con valores de ejemplo de tu especificación OpenAPI. El valor predeterminado es false.

boolean

Si se generan muestras de código para endpoints a partir de tu especificación de API. El valor predeterminado es true. Cuando se establece en false, solo aparecen en el área de pruebas las muestras de código escritas manualmente (desde x-codeSamples en OpenAPI o componentes <RequestExample> en MDX).

object

Configuración para páginas de API creadas a partir de archivos MDX en lugar de especificaciones OpenAPI.

Mostrar api.mdx

object

Configuración de autenticación para solicitudes de API basadas en MDX.

Mostrar auth

"bearer" | "basic" | "key" | "cobo"

Método de autenticación para las solicitudes de API.

string

Nombre del parámetro de autenticación para las solicitudes de API.

string or array

URL base que se antepone a las rutas relativas en los campos de frontmatter api a nivel de página. No se utiliza cuando el frontmatter contiene una URL completa.

Ejemplo

docs.json

{
  "api": {
    "openapi": ["openapi/v1.json", "openapi/v2.json"],
    "playground": {
      "display": "interactive"
    },
    "params": {
      "expanded": "all",
      "post": ["nullable", "x-internal"]
    },
    "url": "full",
    "examples": {
      "languages": ["curl", "python", "javascript", "go"],
      "defaults": "required",
      "prefill": true,
      "autogenerate": true
    }
  }
}

Primeros pasos

Crear contenido

Administra tu sitio

Agente

Assistant

Contenido preparado para agentes

Búsqueda y SEO

Documentar APIs

Integraciones

Referencia

Configuración de la API

Ajustes

`api`

Ejemplo

​Ajustes

​api

​Ejemplo

Ajustes

`api`

Ejemplo