> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tess.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Qué es una especificación OpenAPI y cómo conseguir la tuya

> Una guía en lenguaje sencillo sobre el archivo que Tess lee cuando armas un servidor Custom API.

Esta página es para quien no construye APIs. Explica el archivo que Tess pide en [Custom API](https://docs.tess.im/es/custom-api.md).

## Qué es el archivo

Una API es una forma de que un programa le pida algo a otro programa, por ejemplo "leer el estado" o "crear un registro".

Una **especificación OpenAPI** es el manual estándar de esa API. Es un archivo, en JSON o YAML. El archivo lista:

* la **dirección base** desde la que salen las llamadas
* las **acciones**, también llamadas endpoints, como "leer el estado"
* las **entradas** que espera cada acción
* las **salidas** que devuelve cada acción

Tess lee ese archivo y convierte cada acción en una herramienta que el chat o un agente puede llamar. Eso vale solo para las acciones escritas en `paths`. Las notas que escribes en el diálogo de Custom API no agregan ni quitan acciones. Lo hace el archivo.

## Un archivo que Tess acepta

El archivo más pequeño tiene cuatro piezas. Las palabras del archivo son fijas. No traduzcas `openapi`, `info` ni `paths`.

```yaml theme={null}
openapi: 3.0.3
info:
  title: Status
  version: 1.0.0
paths:
  /status:
    get:
      operationId: getStatus
      summary: Read the service status
      responses:
        "200":
          description: OK
```

* `openapi: 3.0.3` dice que esto es OpenAPI versión 3. Tess acepta 3, o una versión que empieza por `3.`
* `info` es el nombre de la API. Tess exige este bloque.
* `paths` lista las acciones. Tess exige al menos una.
* `get` es la acción. Tess también acepta `put`, `post`, `delete`, `patch`, `head`, `options` y `trace`.

El mismo archivo en JSON, para pegarlo en Custom API:

```json theme={null}
{
  "openapi": "3.0.3",
  "info": { "title": "Status", "version": "1.0.0" },
  "paths": {
    "/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "Read the service status",
        "responses": { "200": { "description": "OK" } }
      }
    }
  }
}
```

En Custom API igual completas **Base URL**, por ejemplo `https://api.example.com`. El archivo de arriba solo describe la acción `/status`.

## Qué acepta Tess

| Regla | Detalle |
| - | - |
| Versión | Solo OpenAPI 3 |
| Tipo de archivo | `.json`, `.yaml` o `.yml`, o el texto pegado en el diálogo |
| Tamaño | Hasta 2 MB |
| Contenido | Un bloque `info`, un bloque `paths` y al menos una acción |

Swagger 2.0 es un formato antiguo. Tess lo rechaza con este mensaje:

**Este archivo usa un formato antiguo (Swagger 2.0). Envía la versión OpenAPI 3 o pide a quien ofrece la API que la actualice.**

## Dónde conseguir el archivo

1. Pídelo al equipo que cuida la API, o a la empresa que la vende. Di que necesitas la spec **OpenAPI 3**, en JSON o YAML.
2. Abre la documentación para desarrolladores del servicio y busca **OpenAPI**, **Swagger** o **API spec**.
3. Prueba direcciones habituales de ese servicio, como un enlace que termina en `/openapi.json` o `/swagger.json`.
4. Muchas herramientas de API exportan este archivo. El nombre del botón depende de la herramienta. Pregunta al proveedor qué exportación es OpenAPI 3.

## Cómo ver la versión

Abre el archivo en cualquier editor de texto y lee las primeras líneas.

OpenAPI 3 empieza así:

```yaml theme={null}
openapi: 3.0.3
```

o, en JSON, `"openapi": "3.0.3"`.

Swagger 2.0 empieza así:

```yaml theme={null}
swagger: "2.0"
```

Si ves `swagger: "2.0"`, Tess no acepta el archivo hasta que se convierta.

## Convertir Swagger 2.0 a OpenAPI 3

Tess no convierte el archivo. Swagger Editor sí. Estas etiquetas salen del código actual de Swagger Editor.

1. Abre [editor.swagger.io](https://editor.swagger.io).
2. Abre **File**, después **Import File**, y elige tu archivo Swagger 2.0. También puedes pegar el archivo en el editor.
3. Abre **Edit**, después **Convert to OpenAPI 3.0.x**. Ese elemento solo aparece cuando el editor tiene un archivo Swagger 2.0. Queda oculto si el archivo ya es OpenAPI 3.
4. Se abre un diálogo titulado **Convert to OpenAPI 3.0.x**. Dice que la conversión usa la Swagger Converter API, que el contenido del editor se envía a ese conversor y que el texto del editor se sustituye por el resultado.
5. Cuando el texto cambie, comprueba que la primera línea sea `openapi:` y una versión que empiece por `3`.
6. Abre **File**, después **Save (as JSON)** o **Save (as YAML)**, y usa esa descarga en Custom API.

El editor envía el archivo al conversor público en `https://converter.swagger.io/api/convert`. No uses este camino para una spec que no puedes compartir fuera de la empresa. Pide al proveedor un archivo OpenAPI 3.

## Si no hay spec

Pide al proveedor un archivo OpenAPI 3. Tess no inventa la lista de acciones.

Si el servicio ya ofrece un servidor MCP, no necesitas este archivo. Añade el servidor en [Custom MCP](https://docs.tess.im/es/mcp-custom.md).

## Cuando se rechaza el archivo

| Qué pasó | Qué probar |
| - | - |
| El mensaje dice que el archivo es Swagger 2.0 | Conviértelo con los pasos de arriba, o pide OpenAPI 3. |
| El mensaje dice que el archivo no parece OpenAPI | Revisa `openapi`, `info` y `paths`, y que exista al menos una acción. |
| El mensaje dice que el atajo YAML no se admite | Pide el archivo JSON, a menudo llamado `openapi.json` o `swagger.json`. |
| El mensaje dice que el archivo supera 2 MB | Pide un archivo más pequeño, solo con las acciones que vas a usar. |
| El mensaje dice que la dirección de la API no es válida | Corrige **Base URL** en [Custom API](https://docs.tess.im/es/custom-api.md). Tiene que ser una dirección `http` o `https` que Tess pueda llamar. |
| El navegador dice que el tipo de archivo es incorrecto | Usa `.json`, `.yaml` o `.yml`. |

Volver al formulario: [Custom API](https://docs.tess.im/es/custom-api.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.