Playground da API
Teste endpoints da API na documentação com o playground interativo: preencha parâmetros, veja exemplos de código em tempo real e envie requisições reais.
O playground da API adiciona um botão interativo "Try it" às páginas de endpoint da API. Os desenvolvedores preenchem parâmetros, veem 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 fica ativado por padrão, sem necessidade de configuração em docs.json. Todas as páginas com um campo openapi: ou api: no frontmatter exibem o botão "Try it". Não é necessário configurar o CORS.
Modos de exibição
O campo display controla o que o playground pode fazer:
| Modo | Botão "Try it" | Preencher parâmetros | Código em tempo real | Enviar requisição |
|---|---|---|---|---|
"interactive" (padrão) | ✓ | ✓ | ✓ | ✓ |
"simple" | ✓ | ✓ | ✓ | ✗ |
"none" | ✗ | ✗ | ✗ | ✗ |
Experiência completa do playground. Os desenvolvedores preenchem parâmetros, veem exemplos de código serem atualizados em tempo real e enviam requisições HTTP reais. As respostas aparecem em linha, com códigos de status, duração e corpos formatados.
{
"api": {
"playground": {
"display": "interactive"
}
}
}Autenticação
O playground exibe um campo de autenticação no início do formulário de parâmetros quando sua API exige autenticação, configurada por meio de api.mdx.auth.method em docs.json. Os desenvolvedores inserem a chave ou o token da API no modal.
As credenciais permanecem apenas na memória durante a sessão atual. Elas nunca são salvas em localStorage nem persistidas entre visitas.
Preenchimento prévio de valores de exemplo
O playground pode pré-preencher os valores example dos parâmetros e dos corpos das requisições na sua especificação OpenAPI:
{
"api": {
"examples": {
"prefill": true
}
}
}Assim, os desenvolvedores começam com valores realistas em vez de campos vazios.
Substituição por página
Substitua o modo de exibição global em páginas individuais usando o campo playground no frontmatter:
---
title: Create Ticket
openapi: POST /tickets
playground: interactive
---
Use essa opção para desativar o playground globalmente e ativá-lo em endpoints de demonstração específicos, ou vice-versa.
| Frontmatter | Comportamento |
|---|---|
playground: interactive | Playground completo nesta página |
playground: simple | Playground apenas com código nesta página |
playground: none | Sem playground nesta página |
Como funciona
O playground é aberto como um modal em tela cheia. A página da documentação permanece intacta ao fundo.
Os parâmetros de caminho, consulta, cabeçalho e corpo aparecem como campos de formulário. Os campos obrigatórios são identificados. A URL base é obtida do campo servers da sua especificação OpenAPI.
Os exemplos de código são gerados novamente enquanto você digita, em cada linguagem configurada. Copie qualquer exemplo com um clique.
No modo interativo, clique em Send (ou pressione Ctrl/Cmd+Enter) para executar a requisição. A resposta aparece abaixo, com o código de status, a duração e o corpo formatado.

A URL recebe ?playground=open enquanto o playground está aberto. Compartilhe-a para direcionar outras pessoas diretamente à visualização do playground de um endpoint.
Vários servidores
Um seletor de servidor aparece ao lado da URL do endpoint quando a especificação de um endpoint lista mais de uma entrada em servers (produção e sandbox, por exemplo). A seleção do leitor define a URL base, o botão para copiar a URL, os exemplos de código na página e a requisição enviada pelo playground.
Endpoints com apenas um servidor não exibem o seletor nem aumentam o peso da página.
Atalhos de teclado
| Atalho | Ação |
|---|---|
Ctrl/Cmd + Enter | Enviar requisição |
Escape | Fechar o playground |
Compatibilidade com os dois tipos de página de API
O playground funciona em páginas que usam o formato openapi: ou api: no frontmatter:
O Jamdesk obtém os parâmetros e esquemas da sua especificação OpenAPI. Não é necessário configurar nada.
---
openapi: POST /tickets
---Desenvolvimento local
O playground funciona apenas em produção. jamdesk dev exibe os botões "Try it". Ao clicar em um deles, uma breve notificação aparece em vez de abrir o modal. Faça o deploy da documentação para usar o playground completo.
Teste ao vivo
Este site está com o playground ativado. Abra a página Exemplo de OpenAPI e clique em "Try it" para enviar uma requisição à API de demonstração.
