Esempio OpenAPI
Visualizza una pagina endpoint OpenAPI generata in tempo reale e scopri come Jamdesk rende richieste, risposte e autenticazione direttamente dalla specifica.
Create a new ticket for a customer issue or request.
Body
customer_idstringrequiredCustomer identifier in Acme.
subjectstringrequiredShort summary of the issue.
priority"low" | "normal" | "high" | "urgent""low" | "normal" | "high" | "urgent"tagsarray<string>messagestringrequiredDetailed problem description.
Response
Ticket created
idstringcustomer_idstringsubjectstringprioritystringstatus"open" | "pending" | "resolved""open" | "pending" | "resolved"tagsarray<string>messagestringcreated_atstring<date-time>updated_atstring<date-time>Questa pagina mostra un endpoint attivo generato da una specifica OpenAPI. Lo schema della richiesta, i modelli di risposta e gli esempi di codice nel pannello a destra vengono generati automaticamente dalla specifica, senza dover scrivere nulla manualmente.
Questo esempio usa l'API di supporto Acme. Aggiorna api.openapi nel tuo docs.json in modo che punti al tuo file di specifica per generare endpoint reali.
Documentazione multilingue? Fornisci un file <spec>.<lang>.<ext> accanto alla specifica di origine, ad esempio example-api.fr.yaml, e Jamdesk mostrerà la versione tradotta quando gli utenti visualizzano la pagina nel percorso /fr/.... Consulta la guida Traduzione delle specifiche OpenAPI.
Questa pagina ha API Playground abilitato. Fai clic su Try it sull'endpoint sopra per testare l'API in tempo reale.
Elementi generati
Da una singola riga openapi nel frontmatter, Jamdesk genera automaticamente:
- Un badge dell'endpoint che mostra il metodo e il percorso con codifica a colori
- Documentazione dei parametri di percorso, query, intestazione e corpo
- Schemi di richiesta e risposta, inclusi oggetti e array annidati
- Esempi di codice in cURL, Python, JavaScript, Go, Ruby, C#, Java, Rust e PHP, configurabili tramite
api.examples.languages - Dettagli di autenticazione ricavati dagli schemi di sicurezza della specifica
Tutti i riferimenti $ref nella specifica vengono risolti automaticamente, così puoi organizzare gli schemi con components/schemas come di consueto.
Le descrizioni nella specifica vengono visualizzate come Markdown, non stampate come testo non elaborato: le descrizioni di operazioni, parametri, corpi delle richieste, risposte e schemi supportano tutte lo stesso grassetto, codice, elenchi, link e tabelle GFM che useresti in una pagina .mdx.
Configurazione di OpenAPI
Inserisci la specifica OpenAPI 3.x, in formato YAML o JSON, nella directory openapi/, registrala in docs.json sotto api.openapi, quindi aggiungi openapi: /openapi/your-spec.yaml METHOD /path al frontmatter di qualsiasi pagina. Consulta la guida alla configurazione di OpenAPI per tutti i dettagli.
Generare una pagina per ogni operazione
Invece di creare una pagina per ogni endpoint, collega una scheda di navigazione alla specifica e lascia che Jamdesk generi l'intero riferimento:
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": { "source": "/openapi/api.yaml", "generate": true }
}
]
}
}Ogni operazione riceve una pagina e la barra laterale viene raggruppata per tag. I file .mdx salvati hanno la precedenza in caso di conflitto tra slug, quindi puoi adottare questa configurazione una pagina alla volta; inoltre, quando rinomini un percorso nella specifica, il vecchio URL viene reindirizzato invece di interrompersi. Consulta navigation openapi per le regole complete e i limiti attuali.
Scrivi la tua specifica in YAML? Passala attraverso il validatore YAML gratuito per individuare errori di indentazione e sintassi prima che la build la analizzi.