Integrazione di Swagger 3 in un’applicazione REST con Spring Boot

Oggi la maggior parte delle applicazioni web si stanno sviluppando come moduli separati (back-end/front-end). In questo tipo di scenario, dovremmo avere una documentazione adeguata con informazioni, leggibili e facili da usare. In questo tutorial esamineremo Swagger 3.0 per i servizi REST di Spring Boot

Per descrivere l'implementazione di Swagger, utilizziamo l'applicazione CRUD implementata in precedenti tutorial utilizzando Spring Boot (vedi: API REST SpringBoot 3 con autenticazione JWT e Ruoli). In questo tutorial spiegherò solo l'integrazione di Swagger. Prima di iniziare l’integrazione vediamo cos’è Swagger ed a cosa serve.

Cos’è Swagger

Swagger è una libreria Open Source che ci permette di documentare gli endpoint delle nostre API REST ed è utilizzabile in moltissimi linguaggi quali Node.js, Spring Java e Python.

In particolare Swagger implementa la Specifica OpenAPI (conosciuta originariamente come la Specifica Swagger) la quale è una specifica per file di interfaccia leggibili dalle macchine per descrivere, produrre, consumare e visualizzare servizi web RESTful.

Il framework Swagger comprende una serie di tool Open Source:

Swagger Editor: un editor che ci permette di descrivere le nostre API REST in linguaggio JSON o YAML all’interno del nostro browser ed avere una anteprima real-time della documentazione prodotta;

Swagger UI: una collezione di asset HTML, CSS e Javascript che viene generata automaticamente dalla documentazione della nostra API (che deve essere conforme allo standard OpenAPI);

Swagger Codegen: genera automaticamente stub per la parte client e server a partire dalla specifica OpenAPI.

Integrazione delle dipendenze

Per poter procedere all'integrazione dobbiamo aggiungere le dipendenze Swagger 3 relative a Springfox nel pom.xml del nostro progetto.

<dependency>
	<groupId>org.springdoc</groupId>
	<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
	<version>2.0.3</version>
</dependency>

Configurazione di Swagger 3.0

Prima di passare alla configurazione, dobbiamo creare una classe chiamata SwaggerConfiguration.java (puoi usare anche un nome diverso ). Nel caso del nostro tutorial l’ho inserita all'interno del package .swagger. Di seguito l'implementazione e i relativi commenti passo-passo:

@Configuration
public class SwaggerConfiguration {

    @Value("${saverioriotto.openapi.dev-url}")
    private String devUrl;

    @Value("${saverioriotto.openapi.prod-url}")
    private String prodUrl;

    @Bean
    public OpenAPI myOpenAPI() {
        Server devServer = new Server();
        devServer.setUrl(devUrl);
        devServer.setDescription("Server URL in Development environment");

        Server prodServer = new Server();
        prodServer.setUrl(prodUrl);
        prodServer.setDescription("Server URL in Production environment");

        Contact contact = new Contact();
        contact.setEmail("[email protected]");
        contact.setName("Saverio Riotto");
        contact.setUrl("https://blog.saverioriotto.it");

        License mitLicense = new License().name("MIT License").url("https://blog.saverioriotto.it");

        Info info = new Info()
                .title("Tutorial Management API")
                .version("1.0")
                .contact(contact)
                .description("This API exposes endpoints to manage tutorials.").termsOfService("https://blog.saverioriotto.it")
                .license(mitLicense);

        return new OpenAPI().info(info).servers(List.of(devServer, prodServer));
    }
}

Permessi di accesso a Swagger

Nel caso del nostro progetto di partenza, essendo che le API sono protette da JWT, dobbiamo aggiungere i permessi per l’accesso pubblico alle risorse di Swagger. Per fare questo dobbiamo aggiungere alcune informazione sulla classe WebSecurityConfig.java:

     http.cors(cors-> cors.disable()).csrf(csrf-> csrf.disable())
                .authorizeRequests()
                .requestMatchers("/api/auth/**").permitAll()
                .requestMatchers("/api/test/**").permitAll()
                .requestMatchers("/api/libro/**").permitAll()
                .requestMatchers("/swagger-ui/**").permitAll()
                .requestMatchers("/v3/api-docs/**").permitAll()
                .anyRequest().authenticated();
        http.addFilterBefore(authenticationJwtTokenFilter(), UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }

Avvio dell'applicazione con supporto Swagger 3.0

Abbiamo completato la configurazione di base a livello di codice. Ora possiamo eseguire questo progetto come applicazione Spring Boot. Una volta avviata l'applicazione, possiamo visitare il seguente URL nel browser:

http://localhost:8080/swagger-ui/index.html

A questo punto dovremmo vedere l'interfaccia di Swagger 3.0 che permette la gestione delle API con relative informazioni.

API-DOCS Swagger

La maggior parte delle volte abbiamo bisogno di usare Swagger API-DOCS. È una risposta JSON con diverse coppie chiave-valore. Per ottenere ciò possiamo anche quì visitare il seguente URL nel browser:

http://localhost:8080/v3/api-docs?group=global

Conclusioni

In questo articolo, abbiamo configurato Swagger 3 per generare documentazione di un'API REST di Spring. La lista completa dei parametri e tutto quello di cui hai bisogno per personalizzare la tua configurazione Swagger 3, li trovi alla pagina Swagger 3 Docs

Il codice sorgente completo del tutorial lo trovi su Github.

* Obbligatorio

Invia