​
Panoramica

L’API playground è un ambiente interattivo che consente agli utenti di testare ed esplorare gli endpoint della tua API. Gli sviluppatori possono comporre richieste, inviarle e visualizzare le risposte senza uscire dalla documentazione.
API playground per l'endpoint che avvia un aggiornamento.
Il playground viene generato automaticamente dalla tua specifica OpenAPI o dallo schema AsyncAPI, quindi qualsiasi aggiornamento alla tua API si rifletterà automaticamente nel playground. Puoi anche creare manualmente pagine di riferimento dell’API dopo aver definito un URL di base e un metodo di autenticazione nel file docs.json. Consigliamo di generare l’API playground a partire da una specifica OpenAPI. Consulta OpenAPI Setup per maggiori informazioni sulla creazione del tuo documento OpenAPI.

​
Guida introduttiva

1

Aggiungi il file della specifica OpenAPI.

Verifica che il file della specifica OpenAPI sia valido utilizzando lo Swagger Editor o il Mint CLI.
/your-project
  |- docs.json
  |- openapi.json
2

Configura `docs.json`.

Aggiorna docs.json per fare riferimento alla tua specifica OpenAPI. Aggiungi la proprietà openapi a qualsiasi elemento della navigazione per popolare automaticamente la documentazione con una pagina per ogni endpoint definito nel documento OpenAPI.In questo esempio viene generata una pagina per ciascun endpoint definito in openapi.json, organizzata nel gruppo “API reference” della navigazione.
"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}
Per generare pagine solo per determinati endpoint, elencali nella proprietà pages dell’elemento di navigazione.Questo esempio genera pagine solo per gli endpoint GET /users e POST /users. Per generare le pagine di altri endpoint, aggiungili all’array pages.
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
Personalizzazione del playground

Puoi personalizzare l’API playground definendo le seguenti proprietà in docs.json.
​
playground
object
Configurazione dell’API playground.
​
examples
object
Configurazione degli esempi API generati automaticamente.

​
Esempio di configurazione

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required"
   }
 }
}
Questo esempio configura l’API playground come interattivo, con snippet di codice per cURL, Python e JavaScript. Negli snippet vengono mostrati solo i parametri obbligatori.

​
Pagine endpoint personalizzate

Quando ti serve un controllo più fine sulla documentazione della tua API, usa l’estensione x-mint nella specifica OpenAPI oppure crea pagine MDX dedicate per i singoli endpoint. Entrambe le opzioni ti permettono di:
  • Personalizzare i metadati della pagina
  • Aggiungere contenuti aggiuntivi come esempi
  • Controllare il comportamento dell’API playground per pagina
L’estensione x-mint è consigliata per generare automaticamente tutta la documentazione della tua API dalla specifica OpenAPI e mantenerla in un unico file. Le pagine MDX individuali sono consigliate per API piccole o quando vuoi sperimentare modifiche a livello di singola pagina. Per maggiori informazioni, vedi x-mint extension e MDX Setup.

​
Approfondimenti

  • Configurazione di AsyncAPI per ulteriori informazioni sulla creazione dello schema AsyncAPI e la generazione delle pagine di riferimento per WebSocket.