Playground da API
Teste endpoints da API diretamente na documentação: preencha parâmetros, veja exemplos de código ao vivo e envie requisições reais.
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.
{
"api": {
"playground": {
"display": "interactive"
}
}
}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:
{
"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:
---
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.
---
openapi: POST /tickets
---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 e clique em "Try it" para vê-lo em ação com a API de demonstração.