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

Esta página es para quien no construye APIs. Explica el archivo que Tess pide en Custom API.

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.

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:

{
  "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

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.
Abre la documentación para desarrolladores del servicio y busca OpenAPI, Swagger o API spec.
Prueba direcciones habituales de ese servicio, como un enlace que termina en /openapi.json o /swagger.json.
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í:

openapi: 3.0.3

o, en JSON, "openapi": "3.0.3". Swagger 2.0 empieza así:

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.

Abre editor.swagger.io.
Abre File, después Import File, y elige tu archivo Swagger 2.0. También puedes pegar el archivo en el editor.
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.
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.
Cuando el texto cambie, comprueba que la primera línea sea openapi: y una versión que empiece por 3.
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.

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

Connectors

MCP & API