2012-02-08 4 views
34

Sto cercando uno strumento che possa aiutarmi a generare documentazione API RESTful. Il mio server è scritto in Java e utilizza il framework Spring MVC. Non ho VISTE nel mio server. È un servizio RESTful al 100% e tutto ciò che fa è consumare JSON e sputa JSON.Spring REST API Documentation using Swagger

Mi chiedevo se Swagger è compatibile con le annotazioni Spring?

risposta

21

Attualmente non è disponibile un modulo di swagger MVC Spring (almeno da Wordnik), ma in generale, abilitare lo swagger su un servizio REST basato su JVM è piuttosto semplice.

Il supporto del server Swagger è diviso in due parti: il server principale e l'integrazione con il servizio REST. Vedi lo Swagger github repo. Il nucleo di Swagger definisce il documento che rappresenta il servizio REST, i parametri, i valori consentiti, le operazioni HTTP, ecc. L'integrazione del server collega questo documento alla struttura del framework REST. Wordnik usa Jersey via JAX-RS e rilascia swagger-jaxrs per fare questa integrazione. C'è anche un modulo Swagger-Play che verrà rilasciato a breve nel repository del modulo Play.

Se si desidera attivare spavalderia su un altro quadro REST (come Spring MVC), si segue questa procedura:

1) generare un lettore di API per generare un oggetto com.wordnik.swagger.core.Documentation. Vedi la versione JAX-RS e quella per play.

2) Creare un endpoint REST che restituisca una versione JSON/XML dell'oggetto Documentation al client. Ancora, JAX-RS e play.

3) Aggiungere un filtro per intercettare le richieste per imporre l'accesso a livello di risorsa o oggetto.

Quindi, in breve, potrebbe essere messo insieme abbastanza facilmente.

+1

E 'possibile creare un modulo basato su Java puro? – tbruyelle

+17

Un modulo SpringMVC per Swagger ora esiste qui: https://github.com/martypitt/swagger-springmvc –

+0

Puoi commettere il tag swagger per favore? Vedi qui: http://stackoverflow.com/documentation/swagger/commit – Stephan

3

Se si è solo dopo aver generato un documento API interattivo (senza la necessità di collaborazione in stile wiki), I/O Docs sarebbe una soluzione migliore richiede molto meno sforzo per impostare, utilizzare e personalizzare, IMHO.

È in esecuzione su nodejs e Redis. Devi solo scrivere uno schema JSON della tua API e genera un sito HTML/JS che descrive la tua API e consente agli sviluppatori di giocarci dal vivo dal proprio browser.

Ho intenzione di ospitare la mia API sul mio server (in quanto richiederebbe a chiunque di installare 2 altri software solo per visualizzare l'API sarebbe pazzesco) ma lo schema JSON stesso ha già una bella struttura leggibile e compatta che penso sarebbe sufficiente per la collaborazione con altri programmatori. È un piccolo progetto.

C'è un similar question che si potrebbe voler controllare.

20

C'è un'implementazione Swagger-SpringMVC in corso here ed esempi here.

La specifica v1.2 è completamente implementata e supportata (ad esempio, i modelli sono generati, con supporto completo per i generici) ed è in fase di sviluppo attivo.

+0

È un paio d'anni dopo. Il progetto di esempio che hai elencato utilizza Swagger 0.7.0 (la versione attuale in questo momento è 0.8.3). Puoi confermare che il progetto di esempio è ancora pertinente? Ho problemi con la configurazione del mio progetto. –

+0

@ steve.hanson 0.8.4 è stato rilasciato e ha aggiornato i collegamenti alla demo di esempio nel file Leggimi. Anche la configurazione è stata enormemente semplificata –

5

Un'altra implementazione di Swagger for Spring MVC è swagger4spring-web.

È simile a Swagger-SpringMVC e supporta tutte le annotazioni Swagger e genera lo schema JSON per i tipi di ritorno e i parametri.Funziona anche senza annotazioni di spavalderia.

3

Swagger 2.0 è l'ultima versione di Swagger.

Ci sono diverse varianti di Swagger ora disponibili per diverse esigenze.

io.swagger è il pacchetto per le librerie spavalderia ed è necessario vasetti primavera separate per accoppiarlo con la Primavera. Questa è la versione 2 di spavalderia.

io.springfox è Springfox Swagger2, in cui viene integrato con spavalderia Spring.

com.mangofactory è spavalderia integrato con il framework Spring Web MVC.