Se stai attualmente utilizzando singole pagine MDX per gli endpoint della tua API, puoi migrare alla generazione automatica delle pagine a partire dalla specifica OpenAPI mantenendo la possibilità di personalizzare le singole pagine. Questo ti aiuta a ridurre il numero di file da mantenere e a migliorare la coerenza della documentazione API. Puoi definire metadati e contenuti per ciascun endpoint nella specifica OpenAPI e organizzare gli endpoint nella navigazione dove preferisci.

​
Migrazione tramite CLI

Il comando mint migrate-mdx è il metodo consigliato per migrare dalle pagine endpoint in MDX alle pagine autogenerate. Questo comando:
  • Analizza la struttura di navigazione del tuo docs.json.
  • Identifica le pagine MDX che generano pagine di endpoint OpenAPI.
  • Estrae il contenuto dai file MDX e lo sposta nell’estensione x-mint della tua specifica OpenAPI.
  • Aggiorna il tuo docs.json per fare riferimento direttamente agli endpoint OpenAPI invece dei file MDX.
  • Elimina i file MDX originali degli endpoint.
Se hai già x-mint definito per un endpoint e disponi anche di una pagina MDX con contenuti per lo stesso endpoint, il contenuto MDX sovrascriverà le impostazioni x-mint esistenti.Se hai più pagine MDX per lo stesso endpoint con contenuti diversi, lo script utilizzerà il contenuto della pagina che compare per ultima nel tuo docs.json.Lo strumento di migrazione non supporta l’anteprima delle modifiche prima di applicarle.
1

Prepara la tua specifica OpenAPI.

Assicurati che la tua specifica OpenAPI sia valida e includa tutti gli endpoint che vuoi documentare.Qualsiasi pagina MDX che vuoi migrare deve avere il frontmatter openapi: che fa riferimento a un endpoint.
Valida il tuo file OpenAPI usando lo Swagger Editor o la Mint CLI.
2

Installa la Mint CLI

Se necessario, installa o aggiorna la Mint CLI.
3

Esegui il comando di migrazione.

mint migrate-mdx

​
Passaggi di migrazione manuale

1

Prepara la specifica OpenAPI.

Assicurati che la tua specifica OpenAPI sia valida e includa tutti gli endpoint che vuoi documentare.Per gli endpoint di cui vuoi personalizzare metadati o contenuto, aggiungi l’estensione x-mint all’endpoint. Vedi x-mint extension per maggiori dettagli.Per gli endpoint che vuoi escludere dalla documentazione, aggiungi l’estensione x-hidden all’endpoint.
Valida il file OpenAPI utilizzando lo Swagger Editor o la Mint CLI.
2

Aggiorna la struttura di navigazione.

Sostituisci i riferimenti alle pagine MDX con gli endpoint OpenAPI nel file docs.json.
"navigation": {
  "groups": [
    {
      "group": "API Reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "overview",
        "authentication",
        "introduction",
        "GET /health",
        "quickstart", 
        "POST /users",
        "GET /users/{id}",
        "advanced-features"
      ]
    }
  ]
}
3

Rimuovi i vecchi file MDX.

Dopo aver verificato che la nuova navigazione funzioni correttamente, rimuovi i file di endpoint MDX di cui non hai più bisogno.
Puoi personalizzare come la documentazione della tua API viene visualizzata nella navigazione.
Combina pagine API generate automaticamente con altre pagine: 
"navigation": {
  "groups": [
    {
      "group": "API Reference",
      "openapi": "openapi.json",
      "pages": [
        "api/overview",
        "GET /users",
        "POST /users", 
        "api/authentication"
      ]
    }
  ]
}

​
Più versioni dell’API

Organizza versioni diverse dell’API usando schede o gruppi: 
"navigation": {
  "tabs": [
    {
      "tab": "API v1",
      "openapi": "specs/v1.json"
    },
    {
      "tab": "API v2", 
      "openapi": "specs/v2.json"
    }
  ]
}

​
Quando usare pagine MDX individuali

Valuta di mantenere pagine MDX individuali quando hai bisogno di:
  • Contenuti personalizzati approfonditi per singolo endpoint, come componenti React o esempi estesi.
  • Layout di pagina unici.
  • Approcci di documentazione sperimentali per endpoint specifici.
Per la maggior parte dei casi d’uso, la navigazione OpenAPI garantisce migliore manutenibilità e coerenza.