Jamdesk Documentation logo

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.

Modal do playground da API com um formulário de parâmetros à esquerda e exemplos de código em tempo real à direita

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:

ModoBotão "Try it"Preencher parâmetrosCódigo em tempo realEnviar 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.

docs.json
{
  "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:

docs.json
{
  "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.

FrontmatterComportamento
playground: interactivePlayground completo nesta página
playground: simplePlayground apenas com código nesta página
playground: noneSem playground nesta página

Como funciona

1
Clique em 'Try it'

O playground é aberto como um modal em tela cheia. A página da documentação permanece intacta ao fundo.

2
Preencha os parâmetros

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.

3
Veja o código ser atualizado

Os exemplos de código são gerados novamente enquanto você digita, em cada linguagem configurada. Copie qualquer exemplo com um clique.

4
Envie a requisição

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.

Playground da API exibindo uma resposta 201 Created com corpo JSON após o envio de uma requisição

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

AtalhoAção
Ctrl/Cmd + EnterEnviar requisição
EscapeFechar 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.

O que vem a seguir?

Exemplo de OpenAPI

Veja um playground ao vivo em uma página de endpoint gerada automaticamente

Referência de docs.json

Referência completa de configuração, incluindo api.playground

Exemplos de requisição e resposta

Páginas de endpoint da API escritas manualmente com componentes MDX

Exemplos de código

Configure quais linguagens aparecem nos exemplos de código