Playground API
Testa gli endpoint API direttamente dalla documentazione con il playground interattivo. Compila i parametri, vedi esempi di codice in tempo reale e invia richieste reali.
Il playground API aggiunge un pulsante interattivo "Try it" alle pagine degli endpoint API. Gli sviluppatori compilano i parametri, vedono aggiornarsi gli esempi di codice in tempo reale e inviano richieste HTTP reali dalla pagina della documentazione.
Gli screenshot mostrano l'interfaccia in inglese.
Avvio rapido
Il playground è attivo per impostazione predefinita, senza alcuna configurazione in docs.json. Ogni pagina con un campo frontmatter openapi: o api: riceve un pulsante "Try it". CORS non richiede alcuna configurazione.
Modalità di visualizzazione
Il campo display controlla cosa può fare il playground:
| Modalità | Pulsante "Try it" | Compila parametri | Codice in tempo reale | Invia richiesta |
|---|---|---|---|---|
"interactive" (predefinita) | ✓ | ✓ | ✓ | ✓ |
"simple" | ✓ | ✓ | ✓ | ✗ |
"none" | ✗ | ✗ | ✗ | ✗ |
Esperienza completa del playground. Gli sviluppatori compilano i parametri, vedono aggiornarsi gli esempi di codice in tempo reale e inviano richieste HTTP reali. Le risposte vengono visualizzate in linea con codici di stato, tempi e corpi formattati.
{
"api": {
"playground": {
"display": "interactive"
}
}
}Autenticazione
Il playground mostra un campo di input per l'autenticazione in cima al modulo dei parametri quando la tua API richiede autenticazione (configurata tramite api.mdx.auth.method in docs.json). Gli sviluppatori inseriscono la propria chiave API o token nella finestra modale.
Le credenziali vengono mantenute solo in memoria per la sessione corrente. Non vengono mai salvate in localStorage né conservate tra una visita e l'altra.
Precompilazione dei valori di esempio
Il playground può precompilare i valori example dei parametri e dei corpi delle richieste nella tua specifica OpenAPI:
{
"api": {
"examples": {
"prefill": true
}
}
}Gli sviluppatori partono da valori realistici invece che da campi vuoti.
Override per pagina
Sovrascrivi la modalità di visualizzazione globale su singole pagine usando il campo frontmatter playground:
---
title: Create Ticket
openapi: POST /tickets
playground: interactive
---Usalo per disattivare il playground globalmente ma attivarlo per specifici endpoint dimostrativi, o viceversa.
| Frontmatter | Comportamento |
|---|---|
playground: interactive | Playground completo su questa pagina |
playground: simple | Playground solo codice su questa pagina |
playground: none | Nessun playground su questa pagina |
Come funziona
Il playground si apre come finestra modale a schermo intero sopra la pagina. La tua pagina della documentazione resta intatta sotto.
I parametri di percorso, query, header e corpo vengono mostrati come campi di un modulo. I campi obbligatori sono contrassegnati. L'URL base viene recuperato dal campo servers della tua specifica OpenAPI.
Gli esempi di codice vengono rigenerati mentre digiti, in ogni linguaggio configurato. Copia qualsiasi esempio con un clic.
In modalità interattiva, clicca su Send (o premi Ctrl/Cmd+Enter) per eseguire la richiesta. La risposta viene visualizzata sotto con codice di stato, durata e corpo formattato.
L'URL riceve ?playground=open mentre il playground è aperto. Condividilo per collegarti direttamente alla vista del playground di un endpoint.
Più server
Un selettore di server compare accanto all'URL dell'endpoint quando la specifica di un endpoint elenca più di una voce in servers (ad esempio produzione e sandbox). La scelta del lettore imposta l'URL base, il pulsante di copia dell'URL, gli esempi di codice della pagina e la richiesta inviata dal playground.
Gli endpoint con un solo server non mostrano il selettore e non aggiungono peso alla pagina.
Scorciatoie da tastiera
| Scorciatoia | Azione |
|---|---|
Ctrl/Cmd + Enter | Invia richiesta |
Escape | Chiudi playground |
Funziona con entrambi i tipi di pagina API
Il playground funziona sulle pagine che usano il formato frontmatter openapi: o api::
Jamdesk recupera parametri e schemi dalla tua specifica OpenAPI. Non serve alcuna configurazione.
---
openapi: POST /tickets
---Sviluppo locale
Il playground funziona solo in produzione. jamdesk dev mostra i pulsanti "Try it". Cliccandone uno compare una breve notifica invece di aprire la finestra modale. Distribuisci la documentazione per usare il playground completo.
Provalo dal vivo
Questo sito ha il playground attivo. Apri la pagina OpenAPI Example e clicca su "Try it" per inviare una richiesta all'API dimostrativa.