Playground API
Testa gli endpoint API dalla documentazione con il playground interattivo: compila i parametri, visualizza esempi di codice e invia richieste reali.
Il playground API aggiunge un pulsante interattivo "Try it" alle pagine degli endpoint API. Gli sviluppatori compilano i parametri, vedono gli esempi di codice aggiornarsi in tempo reale e inviano richieste HTTP reali dalla pagina della documentazione.
Gli screenshot mostrano l'interfaccia in inglese.
Avvio rapido
Il playground è abilitato per impostazione predefinita. Ogni pagina con un campo frontmatter openapi: o api: riceve automaticamente un pulsante "Try it". La gestione di CORS è automatica.
Non è necessaria alcuna configurazione docs.json. Aggiungi un campo openapi: o api: al frontmatter della pagina per visualizzare il playground.
Modalità di visualizzazione
Il campo display controlla le funzionalità disponibili nel 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 gli esempi di codice aggiornarsi in tempo reale e inviano richieste HTTP reali. Le risposte vengono visualizzate inline con codici di stato, durata e body formattati.
{
"api": {
"playground": {
"display": "interactive"
}
}
}Autenticazione
Se l'API richiede l'autenticazione (configurata tramite api.mdx.auth.method in docs.json), il playground mostra un campo di autenticazione nella parte superiore del modulo dei parametri. Gli sviluppatori inseriscono la chiave API o il token direttamente nella finestra.
Le credenziali vengono conservate solo in memoria per la sessione corrente. Non vengono mai salvate in localStorage né mantenute tra una visita e l'altra.
Precompilazione dei valori di esempio
Quando la specifica OpenAPI include valori example per i parametri e i body delle richieste, il playground può precompilarli:
{
"api": {
"examples": {
"prefill": true
}
}
}In questo modo gli sviluppatori risparmiano tempo, visualizzando valori realistici che possono modificare invece di partire da campi vuoti.
Override per pagina
Sostituisci la modalità di visualizzazione globale nelle singole pagine utilizzando il campo frontmatter playground:
---
title: Create Ticket
openapi: POST /tickets
playground: interactive
---È utile quando vuoi disabilitare globalmente il playground ma abilitarlo su endpoint demo specifici, o viceversa.
| Frontmatter | Comportamento |
|---|---|
playground: interactive | Playground completo in questa pagina |
playground: simple | Playground con solo il codice in questa pagina |
playground: none | Nessun playground in questa pagina |
Come funziona
Il playground si apre come overlay modale a schermo intero. La pagina della documentazione resta intatta sotto la finestra.
I parametri del percorso, della query, dell'header e del body vengono mostrati come campi del modulo. I campi obbligatori sono contrassegnati. L'URL di base viene recuperato dal campo servers della specifica OpenAPI.
Mentre digiti, gli esempi di codice vengono rigenerati in tempo reale in tutti i linguaggi configurati. Copia qualsiasi esempio con un solo clic.
In modalità interattiva, fai clic su Send (oppure premi Ctrl/Cmd+Enter) per eseguire la richiesta. La risposta viene visualizzata sotto con il codice di stato, la durata e il body formattato.
Gli screenshot mostrano l'interfaccia in inglese.
Quando il playground è aperto, l'URL viene aggiornato includendo ?playground=open. Condividi questo URL per collegare direttamente qualcuno alla vista del playground di un endpoint.
Più server
Quando la specifica di un endpoint elenca più di una voce in servers, ad esempio produzione e sandbox, accanto all'URL dell'endpoint compare un selettore di server. La scelta del lettore determina l'URL di base, il pulsante per copiare l'URL, gli esempi di codice nella pagina e la richiesta effettivamente inviata dal playground, evitando così di copiare un curl di produzione mentre si consulta la documentazione sandbox.
Gli endpoint con un solo server non cambiano: nessun selettore e nessun peso aggiuntivo per la 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 utilizzano il formato frontmatter openapi: o api::
I parametri e gli schemi vengono recuperati automaticamente dalla specifica OpenAPI. Non è necessaria alcuna configurazione aggiuntiva.
---
openapi: POST /tickets
---Sviluppo locale
Quando esegui jamdesk dev, i pulsanti "Try it" sono visibili, ma il playground è una funzionalità disponibile solo in produzione. Facendo clic su "Try it" nello sviluppo locale viene mostrata una breve notifica invece di aprire la finestra. Esegui il deploy della documentazione per utilizzare il playground completo.
Provalo dal vivo
Questo sito di documentazione ha il playground abilitato. Visita la pagina Esempio OpenAPI e fai clic su "Try it" per provarlo con l'API demo.