Puoi definire manualmente gli endpoint dell’API in singoli file MDX invece di utilizzare una specifica OpenAPI. Questo metodo offre flessibilità per contenuti personalizzati, ma per la maggior parte dei progetti consigliamo di generare la documentazione API da un file di specifica OpenAPI, perché più manutenibile e ricco di funzionalità. Tuttavia, creare pagine MDX per un’API può essere utile per documentare API di piccole dimensioni o per prototipare. Per generare pagine per gli endpoint API utilizzando MDX, configura le impostazioni dell’API in docs.json, crea singoli file MDX per ciascun endpoint e utilizza componenti come <ParamFields /> per definire i parametri. A partire da queste definizioni, Mintlify genera API playground interattivi, esempi di richieste ed esempi di risposte.
1

Configura la tua API

Nel file docs.json, definisci l’URL di base e il metodo di autenticazione:
 "api": {
  "mdx": {
    "server": "https://mintlify.com/api", // string array per più URL di base
    "auth": {
      "method": "key",
      "name": "x-api-key" // opzioni: bearer, basic, key.
    }
  }
}
Se vuoi nascondere l’API playground, usa il campo display. Non è necessario includere un metodo di autenticazione se nascondi il playground.
"api": {
  "playground": {
    "display": "none"
  }
}
Trovi l’elenco completo delle configurazioni API in Settings.
2

Crea le pagine dei tuoi endpoint

Ogni pagina di endpoint API deve avere un corrispondente file MDX. All’inizio di ogni file, definisci title e api:
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
---
Puoi specificare i parametri di percorso aggiungendo il nome del parametro al path, racchiuso tra {}:
https://api.example.com/v1/endpoint/{userId}
Se hai un campo server configurato in docs.json, puoi usare percorsi relativi come /v1/endpoint.
Puoi eseguire l’override, per una singola pagina, della modalità di visualizzazione dell’API playground definita a livello globale aggiungendo playground al frontmatter:
---
title: 'Create new user'
api: 'POST https://api.mintlify.com/user'
playground: 'none'
---
  • playground: 'interactive' - Mostra il playground interattivo.
  • playground: 'simple' - Mostra un endpoint copiabile senza playground.
  • playground: 'none' - Nasconde il playground.
3

Aggiungi gli endpoint alla documentazione

Aggiungi le pagine degli endpoint alla sidebar includendo i percorsi nel campo navigation del file docs.json. Scopri di più su come strutturare la documentazione in Navigation.

​
Abilitare l’autenticazione

Puoi aggiungere un metodo di autenticazione a docs.json per abilitarlo globalmente su tutte le pagine, oppure puoi impostarlo pagina per pagina. Il metodo di autenticazione definito su una pagina ha la precedenza su quello globale se entrambi sono configurati.

​
Token bearer

"api": {
    "mdx": {
      "auth": {
        "method": "bearer"
      }
    }
}

​
Autenticazione Basic

"api": {
    "mdx": {
      "auth": {
        "method": "basic"
      }
    }
}

​
Chiave API

"api": {
    "mdx": {
      "auth": {
        "method": "key",
        "name": "x-api-key"
      }
    }
}

​
None

Il metodo di autenticazione none è utile per disabilitare l’autenticazione su un endpoint specifico dopo aver definito un valore predefinito in docs.json. 
---
title: "Your page title"
authMethod: "none"
---