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

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

> Um guia em linguagem simples sobre o arquivo que a Tess lê quando você monta um servidor Custom API.

Esta página é para quem não constrói APIs. Ela explica o arquivo que a Tess pede em [Custom API](https://docs.tess.im/pt/custom-api.md).

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

```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` 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:

```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" } }
      }
    }
  }
}
```

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

1. 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.
2. Abra a documentação para desenvolvedores do serviço e procure **OpenAPI**, **Swagger** ou **API spec**.
3. Tente endereços comuns nesse serviço, como um link que termina em `/openapi.json` ou `/swagger.json`.
4. 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:

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

ou, em JSON, `"openapi": "3.0.3"`.

Swagger 2.0 começa assim:

```yaml theme={null}
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.

1. Abra [editor.swagger.io](https://editor.swagger.io).
2. Abra **File**, depois **Import File**, e escolha o arquivo Swagger 2.0. Você também pode colar o arquivo no editor.
3. 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.
4. 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.
5. Depois que o texto mudar, confira se a primeira linha é `openapi:` e uma versão que começa com `3`.
6. 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](https://docs.tess.im/pt/mcp-custom.md).

## 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](https://docs.tess.im/pt/custom-api.md). 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](https://docs.tess.im/pt/custom-api.md).


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