Documentazione OpenAPI a Markdown
Converti un documento OpenAPI o Swagger in documentazione di riferimento leggibile in Markdown.
Documentazione OpenAPI a Markdown
Incolla un documento OpenAPI 3 o Swagger 2 — in JSON o YAML — e questo strumento lo converte in un riferimento API Markdown che puoi inserire direttamente in un README, una pagina wiki o un sito di documentazione. Ogni operazione diventa la sua sezione, trasformando una specifica che solo una macchina potrebbe leggere comodamente in qualcosa che un collega o un nuovo sviluppatore può scorrere rapidamente.
L'output include un indice con i link a ogni gruppo ed endpoint, una tabella di parametri (o un semplice elenco) per i parametri di percorso, query, header e cookie, un esempio di corpo della richiesta generato, una tabella dei codici di risposta con le loro descrizioni, e un corpo di risposta di esempio dal primo schema corrispondente. Raggruppa gli endpoint per tag o per il primo segmento del loro percorso, scegli se gli esempi di richiesta si renderanno come corpo JSON o comando curl pronto all'uso, e seleziona la profondità dei titoli dell'endpoint in modo che il risultato si integri in un documento esistente. Un interruttore include o esclude gli endpoint deprecati; un altro esporta ogni schema sotto i componenti (o le definizioni di Swagger) come sua sezione alla fine.
I puntatori "$ref" all'interno dello stesso file vengono seguiti automaticamente per parametri, corpi di richiesta/risposta e schemi, quindi una specifica che si affida ai componenti produce comunque tabelle ed esempi completi anziché stringhe $ref grezze. I riferimenti a un altro file o URL vengono lasciati intatti, poiché nulla qui effettua mai una richiesta di rete. Se il Markdown generato supera il limite di output dello strumento, ricevi un messaggio chiaro anziché una scheda bloccata.
Tutto viene eseguito localmente nel tuo browser — la tua specifica API, che spesso descrive sistemi che non vuoi esporre, non viene mai caricata da nessuna parte. Copia il Markdown, scaricalo come file .txt o invialo a un altro strumento per continuare a lavorarci.