---
title: Exemplo de OpenAPI
description: Veja um endpoint gerado pelo OpenAPI e saiba como o Jamdesk renderiza requisições, respostas e autenticação diretamente da sua especificação.
openapi: /openapi/example-api.yaml POST /tickets
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

Esta página demonstra um endpoint ao vivo gerado a partir de uma [especificação OpenAPI](https://spec.openapis.org/oas/latest.html). O esquema da requisição, os modelos de resposta e os exemplos de código no painel direito são gerados automaticamente a partir da especificação, sem necessidade de criação manual.

<Info>
Este exemplo usa a API de suporte da Acme. Atualize `api.openapi` no seu `docs.json` para apontar para seu próprio arquivo de especificação e gerar endpoints reais.
</Info>

<Info>
**Documentação em vários idiomas?** Forneça um arquivo `<spec>.<lang>.<ext>` ao lado da especificação de origem (por exemplo, `example-api.fr.yaml`) e o Jamdesk renderizará a versão traduzida quando os usuários visualizarem a página em `/fr/...`. Consulte [Tradução de especificações OpenAPI](/pt/setup/languages#traduzindo-especificações-openapi).
</Info>

<Tip>
Esta página tem o [Playground da API](/pt/api-reference/playground) habilitado. Clique em **Try it** no endpoint acima para testar a API ao vivo.
</Tip>

## O que é gerado

A partir de uma única linha `openapi` no frontmatter, o Jamdesk gera automaticamente:

- Um selo de endpoint que mostra o método e o caminho com codificação por cores
- Documentação de parâmetros de caminho, consulta, cabeçalho e corpo
- Esquemas de requisição e resposta, incluindo objetos aninhados e arrays
- Exemplos de código em cURL, Python, JavaScript, Go, Ruby, C#, Java, Rust e PHP (configuráveis por meio de `api.examples.languages`)
- Detalhes de autenticação obtidos dos esquemas de segurança da especificação

Todas as referências `$ref` na especificação são resolvidas automaticamente, para que você possa organizar os esquemas com `components/schemas` normalmente.

## Configurar OpenAPI

Coloque sua especificação OpenAPI 3.x (YAML ou JSON) no diretório `openapi/`, registre-a em `docs.json` em `api.openapi` e adicione `openapi: /openapi/your-spec.yaml METHOD /path` ao frontmatter de qualquer página. Consulte o [guia de configuração do OpenAPI](/pt/setup/directory-structure#openapi) para obter todos os detalhes.

<Tip>
  Escrevendo sua especificação em YAML? Execute-a no [Validador de YAML](https://jamdesk.com/utilities/yaml-validator) gratuito para detectar erros de indentação e sintaxe antes que o build a processe.
</Tip>

## Páginas relacionadas

<Columns cols={2}>
  <Card title="Playground da API" icon="flask-vial" href="/pt/api-reference/playground">
    Habilite testes interativos da API nas páginas de endpoint
  </Card>
  <Card title="Exemplos de requisição/resposta" icon="code" href="/pt/api-reference/request-response-examples">
    Exemplo de endpoint criado manualmente usando componentes MDX
  </Card>
</Columns>

<Columns cols={2}>
  <Card title="Configuração do OpenAPI" icon="file-code" href="/pt/setup/directory-structure#openapi">
    Onde armazenar e referenciar arquivos OpenAPI
  </Card>
  <Card title="Referência de docs.json" icon="file-lines" href="/pt/config/docs-json-reference">
    Referência completa da configuração, incluindo api.openapi
  </Card>
</Columns>

---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://jamdesk-docs.jamdesk.app/api-specs.zip