Esempio OpenAPI
Visualizza un endpoint OpenAPI generato in tempo reale e scopri come Jamdesk esegue il rendering di richieste, risposte e autenticazione dalla tua 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 in tempo reale generato da una specifica OpenAPI. Lo schema della richiesta, i modelli della risposta e gli esempi di codice nel pannello a destra vengono generati automaticamente dalla specifica, senza bisogno di scrivere manualmente alcun contenuto.
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 originale, ad esempio example-api.fr.yaml, e Jamdesk mostrerà la versione tradotta quando gli utenti visualizzano la pagina all'indirizzo /fr/.... Consulta Traduzione delle specifiche OpenAPI.
Questa pagina ha API Playground abilitato. Fai clic su Try it sull'endpoint qui sopra per testare l'API in tempo reale.
Contenuti 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
- La documentazione dei parametri di percorso, query, header e corpo
- Gli schemi della richiesta e della 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 - I 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.
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.
Scrivi la specifica in YAML? Eseguila tramite il validatore YAML gratuito per individuare errori di indentazione e sintassi prima che la build la analizzi.