Swagger con JBoss
2 likes805 views
Il documento descrive come integrare Swagger con un'applicazione JAX-RS utilizzando JBoss, Apache Maven e Resteasy per documentare API RESTful. Viene fornita una guida passo-passo per generare e configurare il progetto, impostare le dipendenze necessarie e creare la documentazione interattiva tramite Swagger UI. Infine, si illustra come utilizzare la chiave di accesso per consultare la documentazione generata delle API.
Swagger con JBoss
- 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!