Playground de API
Teste endpoints de API diretamente na documentação com um playground interativo: preencha parâmetros, veja exemplos de código e envie requisições reais.
O playground de 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 pela 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 é gerenciado 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 em tempo real | 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 em tempo real e enviam requisições HTTP reais. As respostas são exibidas na página com códigos de status, tempo de resposta 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 de API ou o token 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.
Preenchimento prévio de valores de exemplo
Quando sua especificação OpenAPI inclui valores example nos parâmetros e corpos das requisições, o playground pode preenchê-los previamente:
{
"api": {
"examples": {
"prefill": true
}
}
}Isso economiza tempo dos desenvolvedores ao exibir valores realistas que eles podem modificar, 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.
Vários servidores
Quando a especificação de um endpoint lista mais de uma entrada em servers — produção e sandbox, por exemplo — um seletor de servidor aparece ao lado da URL do endpoint. A escolha do leitor define a URL base, o botão de cópia da URL, os exemplos de código na página e a requisição que o playground realmente envia, para que ninguém copie um curl de produção enquanto lê a documentação do sandbox.
Endpoints com um único servidor permanecem inalterados: sem seletor e sem peso adicional na página.
Atalhos de teclado
| Atalho | Ação |
|---|---|
Ctrl/Cmd + Enter | Enviar requisição |
Escape | Fechar playground |
Compatibilidade com os dois tipos de página de 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 em si é um recurso exclusivo de produção. Clicar em "Try it" durante o desenvolvimento local exibe uma breve notificação em vez de abrir o modal. Faça o deploy da sua 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.