---
title: Configuración de la Referencia de API
description: Cómo conectar tu especificación OpenAPI y personalizar la referencia de API generada automáticamente.
url: https://docs.thally.io/es/guides/api-reference-setup
---

# Configuración de la Referencia de API

Cómo conectar tu especificación OpenAPI y personalizar la referencia de API generada automáticamente.

## Agregar tu especificación

Coloca tu archivo de especificación OpenAPI 3.x en la raíz del proyecto como `openapi.yaml` (o `openapi.json`). Luego configúralo en `docs.json`:

```json
{
  "tab": "API Reference",
  "api": {
    "source": "openapi.yaml",
    "tagsOrder": ["Users", "Orders", "Products"],
    "defaultGroup": "General"
  }
}
```

La pestaña de Referencia de API generará automáticamente una página para cada operación en tu especificación.

## Opciones de configuración

| Campo | Requerido | Descripción |
| --- | --- | --- |
| `source` | Sí | Ruta a tu archivo de especificación OpenAPI, relativa a la raíz del proyecto. |
| `tagsOrder` | No | Controla el orden en que aparecen las etiquetas en la barra lateral. Las etiquetas no listadas aparecen después. |
| `defaultGroup` | No | Nombre del grupo para operaciones sin etiquetas. Por defecto es `"Endpoints"`. |
| `overrides` | No | Personalizaciones por operación (ver más abajo). |

## Sobreescritura de operaciones

Puedes personalizar cómo aparecen las operaciones individuales en la barra lateral y la documentación:

```json
{
  "api": {
    "source": "openapi.yaml",
    "overrides": {
      "GET /users": {
        "title": "List users",
        "description": "Fetch all users with pagination.",
        "badge": "Stable"
      },
      "DELETE /users/{id}": {
        "title": "Delete user",
        "badge": "Destructive"
      }
    }
  }
}
```

El formato de la clave es `METHOD /path` — que coincide con el `method` y el `path` de tu especificación OpenAPI.

Campos de sobreescritura disponibles:

- **`title`** — título personalizado de la barra lateral y la página
- **`description`** — descripción personalizada que se muestra debajo del título
- **`badge`** — una etiqueta que se muestra junto al título de la operación
- **`group`** — mover la operación a un grupo diferente en la barra lateral

## Ordenamiento de etiquetas

Por defecto, las operaciones se agrupan por sus `tags` de OpenAPI. El array `tagsOrder` controla el orden en la barra lateral:

```json
"tagsOrder": ["Authentication", "Users", "Orders"]
```

Las etiquetas no listadas en `tagsOrder` aparecen después de las listadas, en el orden en que aparecen por primera vez en la especificación.

## Panel Pruébalo

Cada página de operación de API incluye un botón "Try It" que abre un panel de solicitudes interactivo. Este:

- Rellena previamente los parámetros desde el esquema OpenAPI
- Envía solicitudes a través de un proxy del lado del servidor para evitar problemas de CORS
- Muestra la respuesta con el código de estado, encabezados y cuerpo
- Genera un comando cURL que puedes copiar

No se necesita configuración — funciona automáticamente desde tu especificación.

## Varias especificaciones de API

Un sitio que documenta más de una API puede vincular una especificación OpenAPI
diferente a cada pestaña. La primera pestaña con API mantiene las rutas
predeterminadas en `/api/default/...`; cada pestaña adicional enruta sus operaciones
bajo `/api/<tabId>/...`, donde `tabId` es la versión slug de la etiqueta de la
pestaña.

```json
{
  "tabs": [
    {
      "tab": "REST API",
      "api": {
        "source": "openapi.yaml",
        "tagsOrder": ["Users", "Orders"]
      }
    },
    {
      "tab": "Admin API",
      "api": {
        "source": "admin-openapi.yaml",
        "defaultGroup": "Admin"
      }
    }
  ]
}
```

En este ejemplo, las operaciones REST aparecen bajo `/api/default/...` y las operaciones
Admin bajo `/api/admin-api/...`. Cada pestaña genera su propia
navegación en la barra lateral y cada especificación se analiza de forma
independiente, por lo que las etiquetas, sobreescrituras y grupos se limitan a la
pestaña que los posee.

## Reemplazar la especificación de ejemplo

La plantilla incluye un ejemplo de JSONPlaceholder. Para usar tu propia API:

1. Reemplaza `openapi.yaml` con tu especificación
2. Actualiza el `tagsOrder` en `docs.json` para que coincida con tus etiquetas
3. Agrega los `overrides` que desees
4. Ejecuta `npm run dev` para ver el resultado