Jamdesk Documentation logo

Esempio OpenAPI

Visualizza una pagina endpoint live generata da OpenAPI e scopri come Jamdesk mostra richieste, risposte e autenticazione direttamente dalla tua specifica.

POSThttps://jamdesk-docs.jamdesk.app/api/playground/demo/tickets

Create a new ticket for a customer issue or request.

Loading code example
Loading code example

Body

customer_idstringrequired

Customer identifier in Acme.

subjectstringrequired

Short summary of the issue.

priority"low" | "normal" | "high" | "urgent"
Allowed values: "low" | "normal" | "high" | "urgent"
tagsarray<string>
messagestringrequired

Detailed problem description.

Response

application/json

Ticket created

idstring
customer_idstring
subjectstring
prioritystring
status"open" | "pending" | "resolved"
Allowed values: "open" | "pending" | "resolved"
tagsarray<string>
messagestring
created_atstring<date-time>
updated_atstring<date-time>

Questa pagina è un endpoint live generato da una specifica OpenAPI. Jamdesk genera lo schema della richiesta, i modelli di risposta e gli esempi di codice nel pannello destro a partire dalla specifica.

Questo esempio usa l'API Acme Support. Punta api.openapi in docs.json al tuo file di specifica per generare i tuoi endpoint.

Documentazione multilingua? Fornisci un file <spec>.<lang>.<ext> accanto alla specifica sorgente (ad esempio example-api.it.yaml). Jamdesk mostra la versione tradotta nelle pagine sotto /it/.... Vedi Traduzione delle specifiche OpenAPI.

Questa pagina ha il Playground API abilitato. Clicca Try it sull'endpoint sopra per testare l'API in tempo reale.

Cosa viene generato

Da una sola riga openapi nel frontmatter, Jamdesk genera:

  • Un badge dell'endpoint che mostra metodo e percorso, con codifica a colori
  • Documentazione dei parametri per path, query, header e body
  • Schemi di richiesta e risposta, inclusi oggetti annidati e array
  • Esempi di codice in cURL, Python, JavaScript, Go, Ruby, C#, Java, Rust e PHP (configurabili tramite api.examples.languages)
  • Dettagli di autenticazione presi dagli security scheme della specifica

Jamdesk risolve ogni $ref nella tua specifica. Organizza gli schemi con components/schemas come di consueto.

Jamdesk visualizza le descrizioni della specifica come Markdown, non come testo grezzo. Le descrizioni di operazioni, parametri, request body, risposte e schemi supportano gli stessi grassetto, codice, liste, link e tabelle GFM che useresti in una pagina .mdx.

Configurazione di OpenAPI

Inserisci la tua specifica OpenAPI 3.x (YAML o JSON) nella directory openapi/. Registrala in docs.json sotto api.openapi. Poi aggiungi openapi: /openapi/your-spec.yaml METHOD /path al frontmatter di qualsiasi pagina. Vedi la guida alla configurazione OpenAPI per i dettagli completi.

Genera una pagina per ogni operazione

Punta una scheda di navigazione alla specifica per far generare a Jamdesk l'intera reference, invece di scrivere una pagina per ogni endpoint:

docs.json
{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": { "source": "/openapi/api.yaml", "generate": true }
      }
    ]
  }
}

Ogni operazione ottiene una pagina. La sidebar è raggruppata per tag. I file .mdx committati hanno la precedenza in caso di collisione di slug. Puoi adottarlo una pagina alla volta. Rinominare un percorso nella specifica reindirizza l'URL precedente invece di romperlo. Vedi navigation openapi per le regole complete e i limiti attuali.

Scrivi la specifica in YAML? Passala al YAML Validator gratuito per individuare errori di indentazione e sintassi prima che la build la analizzi.

Pagine correlate

Playground API

Abilita il test interattivo delle API sulle pagine degli endpoint

Esempi di richiesta/risposta

Esempio di endpoint scritto a mano con i componenti MDX

Configurazione OpenAPI

Dove archiviare e referenziare i file OpenAPI

Riferimento docs.json

Riferimento completo della configurazione, inclusa api.openapi