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, visualizzano 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: ottiene automaticamente un pulsante "Try it". CORS viene gestito automaticamente.
Non è necessaria alcuna configurazione docs.json. Aggiungi un campo openapi: o api: al frontmatter della pagina e il playground comparirà.
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, visualizzano gli esempi di codice aggiornarsi in tempo reale e inviano richieste HTTP reali. Le risposte vengono visualizzate in linea con codici di stato, tempi di risposta e corpi 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 input per l'autenticazione nella parte superiore del modulo dei parametri. Gli sviluppatori inseriscono direttamente la chiave API o il token nella finestra modale.
Le credenziali vengono conservate in memoria solo per la sessione corrente. Non vengono mai salvate in localStorage né conservate tra una visita e l'altra.
Precompilazione dei valori di esempio
Quando la specifica OpenAPI include valori example per i parametri e i corpi 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
Esegui l'override della modalità di visualizzazione globale sulle 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 su questa pagina |
playground: simple | Playground con solo il codice su questa pagina |
playground: none | Nessun playground su questa pagina |
Come funziona
Il playground si apre come una finestra modale a schermo intero. La pagina della documentazione rimane intatta sotto di essa.
I parametri del percorso, della query, dell'header e del corpo 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 (o premi Ctrl/Cmd+Enter) per eseguire la richiesta. La risposta viene visualizzata sotto con il codice di stato, la durata e il corpo formattato.
Quando il playground è aperto, l'URL viene aggiornato per includere ?playground=open. Condividi questo URL per collegare direttamente qualcuno alla visualizzazione del playground di un endpoint.
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 modale. 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.