---
title: Playground da API
description: Teste endpoints da API diretamente na documentação: preencha parâmetros, veja exemplos de código ao vivo e envie requisições reais.
---
> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.
O playground da API adiciona um botão interativo "Try it" às páginas de endpoints da API. Os desenvolvedores preenchem parâmetros, veem os exemplos de código serem atualizados em tempo real e enviam requisições HTTP reais diretamente da página da documentação.
As capturas de tela mostram a interface em inglês.
## Início rápido
O playground é ativado por padrão. Todas as páginas com um campo `openapi:` ou `api:` no frontmatter recebem automaticamente um botão "Try it". O CORS é tratado automaticamente.
Nenhuma configuração de `docs.json` é necessária. Adicione um campo `openapi:` ou `api:` ao frontmatter da página para que o playground apareça.
## Modos de exibição
O campo `display` controla o que o playground pode fazer:
| Modo | Botão "Try it" | Preencher parâmetros | Código ao vivo | Enviar requisição |
|------|:-:|:-:|:-:|:-:|
| `"interactive"` (padrão) | ✓ | ✓ | ✓ | ✓ |
| `"simple"` | ✓ | ✓ | ✓ | ✗ |
| `"none"` | ✗ | ✗ | ✗ | ✗ |
Experiência completa do playground. Os desenvolvedores preenchem parâmetros, veem os exemplos de código serem atualizados ao vivo e enviam requisições HTTP reais. As respostas são exibidas inline com códigos de status, duração e corpos formatados.
```json docs.json
{
"api": {
"playground": {
"display": "interactive"
}
}
}
```
Modo somente leitura sem o botão Send. Os desenvolvedores podem preencher parâmetros e copiar os exemplos de código gerados, mas não podem executar requisições. Útil quando sua API exige autenticação que não pode ser compartilhada na documentação.
```json docs.json
{
"api": {
"playground": {
"display": "simple"
}
}
}
```
## Autenticação
Se sua API exigir autenticação (configurada por meio de `api.mdx.auth.method` em `docs.json`), o playground exibirá um campo de entrada de autenticação na parte superior do formulário de parâmetros. Os desenvolvedores inserem a chave ou o token da API diretamente no modal.
As credenciais são mantidas apenas na memória durante a sessão atual. Elas nunca são salvas em `localStorage` nem persistidas entre visitas.
## Pré-preenchimento de valores de exemplo
Quando sua especificação OpenAPI inclui valores `example` em parâmetros e corpos de requisição, o playground pode pré-preenchê-los:
```json docs.json
{
"api": {
"examples": {
"prefill": true
}
}
}
```
Isso poupa tempo dos desenvolvedores ao exibir valores realistas que podem ser modificados, em vez de começar com campos vazios.
## Substituição por página
Substitua o modo de exibição global em páginas individuais usando o campo `playground` do frontmatter:
```mdx
---
title: Create Ticket
openapi: POST /tickets
playground: interactive
---
```
Útil quando você quer desativar o playground globalmente, mas ativá-lo em endpoints de demonstração específicos, ou vice-versa.
| Frontmatter | Comportamento |
|-------------|----------|
| `playground: interactive` | Playground completo nesta página |
| `playground: simple` | Playground somente com código nesta página |
| `playground: none` | Nenhum playground nesta página |
## Como funciona
O playground é aberto como uma sobreposição modal em tela cheia. A página da documentação permanece intacta por baixo.
Os parâmetros de caminho, consulta, cabeçalho e corpo são exibidos como campos de formulário. Os campos obrigatórios são marcados. A URL base é obtida do campo `servers` da sua especificação OpenAPI.
Conforme você digita, os exemplos de código são regenerados em tempo real em todas as linguagens configuradas. Copie qualquer exemplo com um clique.
No modo interativo, clique em Send (ou pressione `Ctrl/Cmd+Enter`) para executar a requisição. A resposta é exibida abaixo com código de status, duração e corpo formatado.
Quando o playground está aberto, a URL é atualizada para incluir `?playground=open`. Compartilhe essa URL para direcionar alguém diretamente à visualização do playground de um endpoint.
## Atalhos de teclado
| Atalho | Ação |
|----------|--------|
| `Ctrl/Cmd + Enter` | Enviar requisição |
| `Escape` | Fechar playground |
## Compatibilidade com os dois tipos de página da API
O playground funciona em páginas que usam o formato de frontmatter `openapi:` ou `api:`:
Os parâmetros e esquemas são obtidos automaticamente da sua especificação OpenAPI. Nenhuma configuração adicional é necessária.
```mdx
---
openapi: POST /tickets
---
```
Os parâmetros são extraídos dos seus componentes ``. A URL base vem de `api.mdx.server` no seu docs.json.
```mdx
---
api: GET /tickets/{ticket_id}
---
```
## Desenvolvimento local
Ao executar `jamdesk dev`, os botões "Try it" ficam visíveis, mas o playground é um recurso exclusivo de produção. Clicar em "Try it" no ambiente de desenvolvimento local exibe uma breve notificação em vez de abrir o modal. Faça o deploy da documentação para usar o playground completo.
## Teste ao vivo
Este site de documentação tem o playground ativado. Visite a página [Exemplo de OpenAPI](/pt/api-reference/openapi-example) e clique em "Try it" para vê-lo em ação com a API de demonstração.
## O que vem a seguir?
Veja um playground ao vivo em uma página de endpoint gerada automaticamente
Referência completa de configuração, incluindo api.playground
Páginas de endpoints da API criadas manualmente com componentes MDX
Configure quais linguagens aparecem nos exemplos de código