O que é uma especificação OpenAPI e como conseguir a sua

Esta página é para quem não constrói APIs. Ela explica o arquivo que a Tess pede em Custom API.

O que é o arquivo

Uma API é um jeito de um programa pedir algo a outro programa, por exemplo “ler o status” ou “criar um registro”. Uma especificação OpenAPI é o manual padrão dessa API. É um arquivo, em JSON ou YAML. O arquivo lista:

o endereço base de onde as chamadas partem
as ações, também chamadas de endpoints, como “ler o status”
as entradas que cada ação espera
as saídas que cada ação devolve

A Tess lê esse arquivo e transforma cada ação em uma ferramenta que o chat ou um agente pode chamar. Isso vale só para ações escritas em paths. As notas que você digita no diálogo de Custom API não acrescentam nem removem ações. O arquivo é que faz isso.

Um arquivo que a Tess aceita

O menor arquivo tem quatro peças. As palavras do arquivo são fixas. Você não traduz openapi, info nem 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 diz que isto é OpenAPI versão 3. A Tess aceita 3, ou uma versão que começa com 3.
info é o nome da API. A Tess exige este bloco.
paths lista as ações. A Tess exige pelo menos uma.
get é a ação. A Tess também aceita put, post, delete, patch, head, options e trace.

O mesmo arquivo em JSON, para colar em 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" } }
      }
    }
  }
}

Em Custom API você ainda preenche Base URL, por exemplo https://api.example.com. O arquivo acima só descreve a ação /status.

O que a Tess aceita

Regra	Detalhe
Versão	Só OpenAPI 3
Tipo de arquivo	`.json`, `.yaml` ou `.yml`, ou o texto colado no diálogo
Tamanho	Até 2 MB
Conteúdo	Um bloco `info`, um bloco `paths` e pelo menos uma ação

Swagger 2.0 é um formato antigo. A Tess recusa com esta mensagem: Este arquivo está num formato antigo (Swagger 2.0). Envie a versão OpenAPI 3, ou peça a quem fornece a API para atualizá-la.

Onde conseguir o arquivo

Peça ao time que cuida da API, ou à empresa que a vende. Diga que você precisa da spec OpenAPI 3, em JSON ou YAML.
Abra a documentação para desenvolvedores do serviço e procure OpenAPI, Swagger ou API spec.
Tente endereços comuns nesse serviço, como um link que termina em /openapi.json ou /swagger.json.
Muitas ferramentas de API exportam esse arquivo. O nome do botão depende da ferramenta. Pergunte ao fornecedor qual exportação é OpenAPI 3.

Como ver a versão

Abra o arquivo em qualquer editor de texto e leia as primeiras linhas. OpenAPI 3 começa assim:

openapi: 3.0.3

ou, em JSON, "openapi": "3.0.3". Swagger 2.0 começa assim:

swagger: "2.0"

Se você vê swagger: "2.0", a Tess não aceita o arquivo até ele ser convertido.

Converter Swagger 2.0 para OpenAPI 3

A Tess não converte o arquivo. O Swagger Editor converte. Estes rótulos vêm do código atual do Swagger Editor.

Abra editor.swagger.io.
Abra File, depois Import File, e escolha o arquivo Swagger 2.0. Você também pode colar o arquivo no editor.
Abra Edit, depois Convert to OpenAPI 3.0.x. Esse item só aparece quando o editor está com um arquivo Swagger 2.0. Ele fica oculto se o arquivo já é OpenAPI 3.
Abre um diálogo com o título Convert to OpenAPI 3.0.x. Ele diz que a conversão usa a Swagger Converter API, que o conteúdo do editor é enviado a esse conversor e que o texto do editor é substituído pelo resultado.
Depois que o texto mudar, confira se a primeira linha é openapi: e uma versão que começa com 3.
Abra File, depois Save (as JSON) ou Save (as YAML), e use esse download em Custom API.

O editor envia o arquivo ao conversor público em https://converter.swagger.io/api/convert. Não use esse caminho para uma spec que você não pode compartilhar fora da empresa. Peça ao fornecedor um arquivo OpenAPI 3.

Se não existe spec

Peça ao fornecedor um arquivo OpenAPI 3. A Tess não inventa a lista de ações. Se o serviço já oferece um servidor MCP, você não precisa deste arquivo. Adicione o servidor em Custom MCP.

Quando o arquivo é recusado

O que aconteceu	O que tentar
A mensagem diz que o arquivo é Swagger 2.0	Converta com os passos acima, ou peça OpenAPI 3.
A mensagem diz que o arquivo não parece OpenAPI	Confira `openapi`, `info` e `paths`, e se existe pelo menos uma ação.
A mensagem diz que o atalho YAML não é aceito	Peça o arquivo JSON, muitas vezes chamado `openapi.json` ou `swagger.json`.
A mensagem diz que o arquivo passa de 2 MB	Peça um arquivo menor, só com as ações que você vai usar.
A mensagem diz que o endereço da API não é válido	Corrija Base URL em Custom API. Precisa ser um endereço `http` ou `https` que a Tess possa chamar.
O navegador diz que o tipo do arquivo está errado	Use `.json`, `.yaml` ou `.yml`.

Voltar ao formulário: Custom API.

Connectors

MCP & API