Qual è il modo migliore per generare una documentazione dell'API REST?

Sto cercando un buon modo per generare documentazione per un'API REST. Non ha bisogno di connettersi realmente con il codice o altro, ma sarebbe fantastico poter scrivere la documentazione come file di testo, puntare lo strumento e generare alcuni documenti da esso.Qual è il modo migliore per generare una documentazione dell'API REST?

Qualcuno là fuori ha qualche idea? So di essere un po 'vago, ma, ad essere onesti, non sono abbastanza sicuro di cosa sto cercando qui - principalmente un modo semplice per gestire la documentazione.

fonte

2010-10-14 Kyle Slattery

Perché è necessario un file di testo con documentazione per generare documentazione? Voglio dire, davvero, perché non scrivi semplicemente documentazione in Open Office o qualcosa del genere e la salva come PDF, XML, ecc.? Altri strumenti, come doxygen, hanno lo scopo di generare documentazione dal codice sorgente e commenti in esso. –

Mi dispiace, avrei dovuto menzionare: voglio generare file HTML da esso, ma preferirei non modificare HTML per generarlo. Sto solo cercando un modo per salvare i documenti in un formato con una formattazione minima (usando Markdown o qualcosa di simile) e poi trasformarlo in un mucchio di file HTML collegati. –

According to Roy:

"A REST API should spend almost all of its descriptive 
effort in defining the media type(s) used for representing 
resources and driving application state, or in defining 
extended relation names and/or hypertext-enabled mark-up 
for existing standard media types."

Self-descrittivo è uno dei vantaggi di riposo.

fonte

2010-10-14 21:49:09 fumanchu

Penso che il punto chiave sia che non esiste un modo standardizzato di documentare un tipo di supporto. Se solo ci fosse. Di certo non può essere generato. –

Anche se non riposare, ho usato Sphinx per documentare un API XML-RPC, che consisteva in un riferimento API e un tutorial. Sphinx aggiunge alcune utili direttive a ReStructuredText per ottenere più o meno ciò che hai chiesto: una raccolta di file di testo formattato ReStructuredText che Sphinx trasforma in HTML e PDF, completo di indice e sommario. La Sfinge è facile da usare e ben documentata; Non penso che sarebbe esagerato affermare che potresti iniziare con questo in circa dieci minuti.

fonte

2010-10-15 16:28:11 ddbeck

Alcuni sistemi RESTful sono effettivamente in grado di scrivere la propria API. Date un'occhiata allo RESTx, che fa proprio questo: scrivete i vostri componenti e poi create nuovi servizi web inviando parametri per quei componenti al server (sia come JSON che tramite un modulo web). Quindi ottieni un URI per quei parametri. Accedendo chiama il componente con i parametri e recuperi i risultati.

In ogni caso, i componenti e i servizi Web RESTful creati ricevono una documentazione generata automaticamente, che è visualizzabile e può essere recuperata in formato HTML o JSON.

fonte

2010-10-15 16:29:47 jbrendel

Qual è il modo migliore per generare una documentazione dell'API REST?

risposta

Problemi correlati