OpenAPI è una specifica per la descrizione delle API. Mintlify supporta documenti OpenAPI 3.0+ per generare documentazione API interattiva e mantenerla aggiornata.

​
Aggiungi un file di specifica OpenAPI

Per documentare i tuoi endpoint con OpenAPI, ti serve un documento OpenAPI valido in formato JSON o YAML che rispetti la specifica OpenAPI 3.0+. Puoi creare pagine API a partire da uno o più documenti OpenAPI.

​
Descrivere la tua API

Consigliamo le seguenti risorse per imparare e creare i documenti OpenAPI.
La Guida OpenAPI di Swagger si riferisce a OpenAPI v3.0, ma quasi tutte le informazioni sono applicabili alla v3.1. Per ulteriori informazioni sulle differenze tra v3.0 e v3.1, consulta l’articolo Migrating from OpenAPI 3.0 to 3.1.0 nel blog di OpenAPI.

​
Specificare l’URL della tua API

Per abilitare funzionalità di Mintlify come l’API playground, aggiungi un campo servers al tuo documento OpenAPI con l’URL di base della tua API. 
{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}
In un documento OpenAPI, i diversi endpoint sono definiti dai relativi path, come /users/{id} o semplicemente /. L’URL di base indica a quale origine vanno concatenati questi path. Per ulteriori dettagli su come configurare il campo servers, consulta API Server and Base Path nella documentazione OpenAPI. L’API playground utilizza questi URL dei server per determinare dove inviare le richieste. Se specifichi più server, un menu a discesa consentirà agli utenti di passare da un server all’altro. Se non specifichi alcun server, l’API playground utilizzerà la modalità semplice, poiché non può inviare richieste senza un URL di base. Se la tua API ha endpoint ospitati su URL diversi, puoi eseguire l’override del campo server per un determinato path o operazione.

​
Specificare l’autenticazione

Per abilitare l’autenticazione nella documentazione e nell’API Playground, configura i campi securitySchemes e security nel tuo documento OpenAPI. Le descrizioni API e l’API Playground aggiungeranno i campi di autenticazione in base alle configurazioni di sicurezza presenti nel documento OpenAPI.
1

Definisci il metodo di autenticazione.

Aggiungi il campo securitySchemes per definire come si autenticano gli utenti.Questo esempio mostra una configurazione per l’autenticazione bearer.
{
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
2

Applica l'autenticazione ai tuoi endpoint.

Aggiungi il campo security per richiedere l’autenticazione.
{
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
I tipi di autenticazione più comuni includono:
  • API Keys: per chiavi in header, query o cookie.
  • Bearer: per token JWT o OAuth.
  • Basic: per nome utente e password.
Se diversi endpoint della tua API richiedono metodi di autenticazione differenti, puoi eseguire l’override del campo security per una determinata operazione. Per ulteriori informazioni sulla definizione e sull’applicazione dell’autenticazione, consulta Authentication nella documentazione OpenAPI.

​
Estensione x-mint

L’estensione x-mint è un’estensione OpenAPI personalizzata che offre un controllo maggiore su come viene generata e visualizzata la documentazione della tua API.

​
Metadati

Puoi sostituire i metadati predefiniti delle pagine API generate aggiungendo x-mint: metadata a qualsiasi operazione. Puoi usare qualsiasi campo di metadati valido nel frontmatter MDX, ad eccezione di openapi: 
{
  "paths": {
    "/users": {
      "get": {
        "summary": "Get users",
        "description": "Retrieve a list of users",
        "x-mint": {
          "metadata": {
            "title": "List all users",
            "description": "Fetch paginated user data with filtering options",
            "og:title": "Display a list of users"
          }
        },
        "parameters": [
          {
            // Parameter configuration
          }
        ]
      }
    }
  }
}

​
Contenuto

Aggiungi contenuto prima della documentazione API generata automaticamente usando x-mint: content: 
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "content": "## Prerequisiti\n\nQuesto endpoint richiede privilegi amministrativi ed è soggetto a limitazione della frequenza.\n\n<Note>Le email degli utenti devono essere univoche in tutto il sistema.</Note>"
        },
        "parameters": [
          {
            // Configurazione del parametro
          }
        ]
      }
    }
  }
}
L’estensione content supporta tutti i componenti e la formattazione MDX di Mintlify.

​
Href

Modifica l’URL della pagina dell’endpoint nella tua documentazione usando x-mint: href: 
{
  "paths": {
    "/legacy-endpoint": {
      "get": {
        "summary": "Legacy endpoint",
        "x-mint": {
          "href": "/deprecated-endpoints/legacy-endpoint"
        }
      }
    },
    "/documented-elsewhere": {
      "post": {
        "summary": "Special endpoint",
        "x-mint": {
          "href": "/guides/special-endpoint-guide"
        }
      }
    }
  }
}
Quando x-mint: href è presente, la voce di navigazione rimanderà direttamente all’URL specificato invece di generare una pagina API.

​
MCP

Esponi selettivamente gli endpoint come strumenti del Model Context Protocol (MCP) usando x-mint: mcp. Abilita solo gli endpoint sicuri per l’accesso pubblico tramite strumenti di IA.
​
mcp
object
Configurazione MCP per l’endpoint.
{
  "paths": {
    "/users": {
      "post": {
        "summary": "Create user",
        "x-mint": {
          "mcp": {
            "enabled": true
          },
          // ...
        }
      }
    },
    "/users": {
      "delete": {
        "summary": "Delete user (admin only)",
        // No `x-mint: mcp` so this endpoint is not exposed as an MCP tool
        // ...
      }
    }
  }
}
Per ulteriori informazioni, consulta Model Context Protocol.

​
Generazione automatica delle pagine API

Aggiungi il campo openapi a qualsiasi elemento della navigazione nel tuo docs.json per generare automaticamente le pagine degli endpoint OpenAPI. Puoi controllare dove queste pagine compaiono nella struttura di navigazione, come sezioni API dedicate o insieme ad altre pagine. Il campo openapi accetta un percorso di file nel repository della documentazione o un URL a un documento OpenAPI ospitato. Le pagine degli endpoint generate hanno questi metadati predefiniti:
  • title: Il campo summary dell’operazione, se presente. Se non è presente un summary, il titolo viene generato a partire dal metodo HTTP e dall’endpoint.
  • description: Il campo description dell’operazione, se presente.
  • version: Il valore version dall’ancora o dalla scheda padre, se presente.
  • deprecated: Il campo deprecated dell’operazione. Se true, un’etichetta “deprecated” apparirà accanto al titolo dell’endpoint nella navigazione laterale e nella pagina dell’endpoint.
Per escludere specifici endpoint dalle pagine API generate automaticamente, aggiungi la proprietà x-hidden all’operazione nella tua specifica OpenAPI.
Esistono due modalità per aggiungere pagine di endpoint alla documentazione:
  1. Sezioni API dedicate: fai riferimento alle specifiche OpenAPI negli elementi di navigazione per creare sezioni API dedicate.
  2. Endpoint selezionati: inserisci specifici endpoint nella navigazione insieme ad altre pagine.

​
Sezioni API dedicate

Genera sezioni API dedicate aggiungendo un campo openapi a un elemento della navigazione senza includere altre pagine. Tutti gli endpoint presenti nella specifica verranno inclusi: 
"navigation": {
  "tabs": [
    {
        "tab": "API Reference",
        "openapi": "https://petstore3.swagger.io/api/v3/openapi.json"
    }
  ]
}
Puoi usare più specifiche OpenAPI in sezioni di navigazione diverse: 
"navigation": {
  "tabs": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Users",
          "openapi": {
            "source": "/path/to/openapi-1.json",
            "directory": "api-reference"
          }
        },
        {
          "group": "Admin",
          "openapi": {
            "source": "/path/to/openapi-2.json",
            "directory": "api-reference"
          }
        }
      ]
    }
  ]
}
Il campo directory è facoltativo e indica dove vengono salvate le pagine API generate nel repository della documentazione. Se non specificato, il valore predefinito è la directory api-reference del repository.

​
Endpoint selettivi

Quando vuoi avere più controllo su dove compaiono gli endpoint nella documentazione, puoi fare riferimento a endpoint specifici nella navigazione. Questo approccio ti consente di generare pagine per gli endpoint API insieme ad altri contenuti.

​
Impostare una specifica OpenAPI predefinita

Configura una specifica OpenAPI predefinita per un elemento di navigazione. Poi fai riferimento agli endpoint specifici nel campo pages: 
"navigation": {
  "tabs": [
    {
      "tab": "Getting started",
      "pages": [
        "quickstart",
        "installation"
      ]
    },
    {
      "tab": "API reference",
      "openapi": "/path/to/openapi.json",
      "pages": [
        "api-overview",
        "GET /users",
        "POST /users",
        "guides/authentication"
      ]
    }
  ]
}
Qualsiasi voce di pagina che corrisponda al formato METHOD /path genererà una pagina dell’API per quell’endpoint utilizzando la specifica OpenAPI predefinita.

​
Ereditarietà delle specifiche OpenAPI

Le specifiche OpenAPI vengono ereditate lungo la gerarchia di navigazione. Gli elementi di navigazione figli ereditano la specifica OpenAPI del padre, a meno che non ne definiscano una propria: 
{
  "group": "API reference",
  "openapi": "/path/to/openapi-v1.json",
  "pages": [
    "overview",
    "authentication",
    "GET /users",
    "POST /users",
    {
      "group": "Orders",
      "openapi": "/path/to/openapi-v2.json",
      "pages": [
        "GET /orders",
        "POST /orders"
      ]
    }
  ]
}

​
Endpoint individuali

Fai riferimento a endpoint specifici senza impostare una specifica OpenAPI predefinita includendo il percorso del file: 
"navigation": {
  "pages": [
    "introduction",
    "user-guides",
    "/path/to/openapi-v1.json POST /users",
    "/path/to/openapi-v2.json GET /orders"
  ]
}
Questo approccio è utile quando ti servono endpoint individuali da specifiche diverse oppure vuoi includere solo alcuni endpoint selezionati.

​
Crea file MDX per le pagine API

Per controllare le singole pagine degli endpoint, crea una pagina MDX per ogni operazione. In questo modo puoi personalizzare i metadati della pagina, aggiungere contenuti, omettere alcune operazioni o riordinare le pagine nella navigazione a livello di pagina. Consulta un esempio di pagina OpenAPI in MDX di MindsDB e come viene visualizzata nella loro documentazione pubblica.

​
Specificare manualmente i file

Crea una pagina MDX per ogni endpoint e specifica quale operazione OpenAPI mostrare usando il campo openapi nel frontmatter. Quando fai riferimento a un’operazione OpenAPI in questo modo, il nome, la descrizione, i parametri, le risposte e l’API playground vengono generati automaticamente dal tuo documento OpenAPI. Se hai più file OpenAPI, includi il percorso del file nel riferimento per assicurarti che Mintlify trovi il documento OpenAPI corretto. Se hai un solo file OpenAPI, Mintlify lo rileverà automaticamente.
Questo approccio funziona indipendentemente dal fatto che tu abbia impostato una specifica OpenAPI predefinita nella navigazione. Puoi fare riferimento a qualsiasi endpoint da qualsiasi specifica OpenAPI includendo il percorso del file nel frontmatter.
Se vuoi fare riferimento a un file OpenAPI esterno, aggiungi l’URL del file al tuo docs.json. 
---
title: "Get users"
description: "Restituisce tutti gli utenti del sistema a cui l’utente ha accesso"
openapi: "/path/to/openapi-1.json GET /users"
deprecated: true
version: "1.0"
---
Il metodo e il path devono corrispondere esattamente alla definizione nella tua specifica OpenAPI. Se l’endpoint non esiste nel file OpenAPI, la pagina sarà vuota.

​
Generazione automatica dei file MDX

Usa lo scraper di Mintlify per generare automaticamente pagine MDX a partire da documenti OpenAPI di grandi dimensioni.
Il tuo documento OpenAPI deve essere valido, altrimenti i file non verranno generati automaticamente.
Lo scraper genera:
  • Una pagina MDX per ogni operazione nel campo paths del tuo documento OpenAPI.
  • Se il tuo documento OpenAPI è in versione 3.1+, una pagina MDX per ogni operazione nel campo webhooks del tuo documento OpenAPI.
  • Un array di voci di navigazione da aggiungere al tuo docs.json.
1

Genera i file `MDX`.

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file>
2

Specifica una cartella di output.

npx @mintlify/scraping@latest openapi-file <path-to-openapi-file> -o api-reference
Aggiungi il flag -o per specificare una cartella in cui salvare i file. Se non viene specificata una cartella, i file verranno salvati nella directory di lavoro.

​
Crea file MDX per gli schemi OpenAPI

Puoi creare pagine dedicate per qualsiasi schema OpenAPI definito nel campo components.schema di un documento OpenAPI: 
---
openapi-schema: OrderItem
---

​
Webhook

I webhook sono callback HTTP che la tua API invia per notificare sistemi esterni quando si verificano eventi. I webhook sono supportati nei documenti OpenAPI 3.1+.

​
Definisci i webhook nella tua specifica OpenAPI

Aggiungi il campo webhooks al documento OpenAPI insieme al campo paths. Per ulteriori informazioni su come definire i webhook, consulta Webhooks nella documentazione OpenAPI.

​
Fare riferimento ai webhook nei file MDX

Quando crei pagine MDX per i webhook, usa webhook invece dei metodi HTTP come GET o POST: 
---
title: "Example webhook"
description: "Triggered when an event occurs"
openapi: "path/to/openapi-file webhook example-webhook-name"
---
Il nome del webhook deve corrispondere esattamente alla chiave definita nel campo webhooks della specifica OpenAPI.