Swagger è un semplice ma potente tool per la documentazione delle nostre RESTful API. Definisce una interfaccia standard e indipendende dal linguaggio, che permette sia a persone che computer di scoprire e comprendere le capacità di un servizio senza accedere al codice sorgente, a documentazione o ispezione del traffico di rete. In questo post creeremo la documentazione per l’API members contenuta nell’applicazione di esempio generata dal modello jboss-javaee6-webapp.

1. Integrazione di Swagger con una applicazione JAX-RS
In questo post vedremo come integrare Swagger con una applicazione JAX-RS. Il software utilizzato è il
seguente:
• JBoss AS 7.1.1.Final
• Apache Maven 3.2.3
• Swagger 1.5.3
• RESTEasy 2.3.2.Final
• Windows 7
Introduzione
Swagger è un semplice ma potente tool per la documentazione delle nostre RESTful API. Definisce una
interfaccia standard e indipendende dal linguaggio, che permette sia a persone che computer di scoprire e
comprendere le capacità di un servizio senza accedere al codice sorgente, a documentazione o ispezione
del traffico di rete. In questo post creeremo la documentazione per l’API members contenuta
nell’applicazione di esempio generata dal modello jboss-javaee6-webapp.
Con maven, nella directory c:progettirest, generiamo il progetto swagger-jboss-sample utilizzando
il comando:
Modifichiamo il file pom.xml in modo tale da impostare la nostra versione di JBoss
Figura 1 - pom.xml
Eseguiamo lo start di JBoss, compiliamo e deployamo l’applicazione con il comando:
c:progettirestswagger-jboss-sample>mvn package jboss-as:deploy
Puntando il browser su http://localhost:8080/swagger-jboss-sample/ dovremmo vedere la
pagina seguente:

2. Figura 2 - Applicazione generata da jboss-javaee6-webapp
Integrazione di Swagger
Nel file pom.xml aggiungiamo le dipendenze necessarie:
Figura 3 - pom.xml

3. Aggiungiamo inoltre il plugin per il download di swagger-ui
Figura 4 - pom.xml
e il plugin per la copia di swagger-ui nella nostra web application:
Figura 5 - pom.xml
Nella directory src/main/webapp creiamo il file swagger-ui.html. Questa pagina utilizza swagger-ui
per creare la documentazione interattiva; come si può vedere dalla figura 6, swagger-ui legge la descrizione
json del servizio e la trasforma in una descrizione human readable.
Figura 6 - swagger-ui.html

4. Creiamo il file web.xml nella directory src/main/webapp/WEB-INF con il seguente contenuto:
Figura 7 - web.xml
Nella directory src/main/java/swagger/jboss/sample/rest cancelliamo il file
JaxRsActivator.java e creiamo i file SampleApplication.java e
ApiAuthorizationFilterImpl.java. Nel metodo getClasses agganciamo le componenti di
swagger (ApiListingResource, SwaggerSerializers) e indichiamo il rest provider della nostra
applicazione (MemberResourceRESTService). Nel costruttore inizializziamo swagger via BeanConfig.
La classe ApiAuthorizationFilterImpl permette l’accesso alla documentazione solo a chi possiede la
relativa chiave. In questo esempio la chiave è 123321.
Figura 8 - SampleApplication.java

5. Nel file index.xhtml sostituiamo rest con api
Figura 9 - index.xhtml
Non ci resta che dire a swagger cosa documentare: annotiamo la classe MemberResourceRESTService
con @Api e @ApiOperation
Figura 10 - MemberResourceRESTService.java
Compiliamo e deployamo; all’indirizzo http://localhost:8080/swagger-jboss-sample/swagger-ui.html
dovremmo vedere la documentazione generata per la nostra REST API:
Figura 11 - Swagger-UI

6. Da questa pagina possiamo consultare tutti i dettagli di ogni operazione; per esempio cliccando
sull’operazione members, otteniamo la schermata in figura 12. Si vede la struttura della risposta e il tasto
Try it out! che permette di invocare l’operazione. Cliccando su Try it out! possiamo vedere il comando
curl utilizzato da swagger per inviare la richiesta, e la relativa risposta (in figura 13).
Figura 12 - Dettagli operazione
Figura 13 - Risposta operazione members

7. La descrizione JSON della REST API, secondo la specifica 2.0, è disponibile al seguente indirizzo:
http://localhost:8080/swagger-jboss-sample/api/swagger.json?api_key=123321
Figura 14 - Descrizione JSON
Nella sezione Riferimenti è riportato il link al quale scaricare il progetto di esempio già configurato con
swagger. Buona documentazione!

8. Riferimenti
http://swagger.io/
https://github.com/swagger-api/swagger-samples/tree/master/java/java-resteasy
http://www.webalice.it/nmastrapasqua/sources/swagger-jboss-sample.zip
http://www.mastertheboss.com/jboss-frameworks/maven-tutorials/jboss-maven/jboss-maven-example-
building-a-java-ee-6-application