Configuración de la API

Configura las especificaciones OpenAPI y AsyncAPI, el área de pruebas interactiva, los ejemplos de código y la autenticación en docs.json.

Usa el campo api en docs.json para configurar qué especificaciones de API están disponibles para generar páginas de API; el área de pruebas interactiva de la API donde los usuarios pueden probar endpoints de API; 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.

api.openapi · 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 y URLs, o un objeto que especifica una fuente y directorio.

Mostrar api.openapi object

source · string

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

directory · string

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

Archivo único

"openapi": "openapi.json"

api.asyncapi · 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

source · string

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

directory · string

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

Archivo único

"asyncapi": "asyncapi.json"

api.playground · object

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

Mostrar api.playground

display · "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

proxy · boolean

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

api.params · object

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

Mostrar api.params

expanded · "all" | "closed"

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

api.url · "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.

api.examples · object

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

Mostrar api.examples

languages · 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.

defaults · "required" | "all"

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

prefill · boolean

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

autogenerate · 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).

api.spec · object

Configuración de visualización de la especificación OpenAPI. Incluye el botón de descarga en las páginas de referencia de API.

Mostrar api.spec

download · boolean

Si se muestra un botón de descarga para la especificación OpenAPI en las páginas de referencia de API. El valor predeterminado es false.

api.mdx · object

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

Mostrar api.mdx

auth · object

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

Mostrar auth

method · "bearer" | "basic" | "key" | "cobo"

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

name · string

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

server · 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"
    },
    "url": "full",
    "examples": {
      "languages": ["curl", "python", "javascript", "go"],
      "defaults": "required",
      "prefill": true,
      "autogenerate": true
    },
    "spec": {
      "download": true
    }
  }
}