In questo articolo voglio farti vedere un modo per documentare le API REST in Spring Boot e utilizzarle da interfaccia web. Se non hai ancora creato la tua prima API, dai un’occhiata a post come creare API RESTful utilizzando Spring Boot.
Springfox e Swagger2
Utilizzare Springfox in un progetto Spring Boot
Per utilizzare la suite springfox all’interno di un progetto Spring Boot, è necessario aggiungere le sue dipendenze e abilitarne la configurazione.
Vediamo di cosa si tratta.
Aggiungere le dipendenze
Per realizzare quanto sto per dire occorrono due dipendenze recuperabili da mvnrepository centrale, una per swagger2 e l’altra per la UI.
Al momento della scrittura di questo post l’ultima versione è la 2.9.2.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
Utilizzeremo queste le librerie springfox per generare in modo automatico l’interfaccia swagger con la quale visualizzare e utilizzare le API, partendo da annotazioni Spring inserite appositamente nelle classi Java.
Aggiungere una configurazione
Per abilitare Swagger2 sulla nostra applicazione Spring Boot è sufficiente aggiungere l’annotazione @EnableSwagger2 della libreria aggiunta, ad esempio, sulla classe dove è presente il metodo main (subito sotto @SpringBootApplication).
@SpringBootApplication
@EnableSwagger2
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}Cosi facendo, all’avvio dell’applicazione, verrà generato un file contenente tutta la documentazione Swagger (in formato Json). Per osservarne il risultato, basta collegarsi alla pagina /v2/api-docs.
All’aspetto sembrerà poco amichevole, ma per fortuna, sarà generata anche la pagina /swagger-ui.html, come vedrai più avanti.
Aggiungere una configurazione personalizzata
Prima di parlare dell’interfaccia UI di Swagger, è giusto chiedersi se, oltre alla configurazione di default, ci sia un modo per personalizzarla. Per farlo, possiamo utilizzare il componente Docket fornito dalla libreria springfox, che fornisce impostazioni predefinite e metodi convenienti per la configurazione.
Per migliorare la leggibilità delle classi del progetto, creiamo un nuovo file SwaggerConfig.java da utilizzare come configurazione per Swagger.
Spostiamo in questa classe Java l’annotazione vista in precedenza per abilitare Swagger2 e creiamo un nuovo Bean di tipo Docket come nell’esempio:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
.apiInfo(this.apiInfo())
.useDefaultResponseMessages(false);
}
private ApiInfo apiInfo() {
ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
apiInfoBuilder.title("REST API");
apiInfoBuilder.description("REST API Generation");
apiInfoBuilder.version("1.0.0");
apiInfoBuilder.license("GNU GENERAL PUBLIC LICENSE, Version 3");
apiInfoBuilder.licenseUrl("https://www.gnu.org/licenses/gpl-3.0.en.html");
return apiInfoBuilder.build();
}
}
Puoi personalizzare a tuo piacimento tutte le informazioni, specificare il package che contiene le API da documentare, tipo .apis(RequestHandlerSelectors.basePackage("it.lateralecloud.controller")).
Puoi decidere di non documentare alcune API, escludendole dall’interfaccia Swagger, come quelle relative a Basic Error Controller generate da Spring .paths(Predicates.not(PathSelectors.regex("/error.*"))), oppure aggiungere un’autenticazione per accedere all’interfaccia.
Tutto quello di cui hai bisogno per configurare correttamente Swagger potrai trovarlo all’interno della pagina Springfox Docs.
Documentare le API
Adesso che abbiamo configurato springfox all’interno dell’applicazione possiamo documentare le API a nostro piacimento.
Questo passaggio non è indispensabile per la generazione della documentazione, infatti, di default vengono documentati tutti i metodi annotati come controller rest.
L’esempio sottostante si riferisce ad una API definita in un’altro articolo in cui viene trattato l’argomento su come creare API RESTful con Spring Boot.
Prendiamo il metodo getById della classe ApplicationUserController e documentiamolo in questo modo:
/**
* Gets by id.
*
* @param id the id
* @return the by id
*/
@GetMapping("/{id}")
@ApiOperation(value = "get user", notes = "get user by id")
public ResponseEntity getById(
@ApiParam(name = "id", value = "Unique user id", required = true) @PathVariable("id") Long id) {
ApplicationUserDto result = this.applicationUserService.getById(id);
return result != null ? ResponseEntity.ok(result) : ResponseEntity.notFound().build();
}Anche in questo caso, potrai approfondire ciò che hai appena visto spulciando nella pagina Springfox Docs.
Utilizzare l'interfaccia Swagger
Possiamo ora avviare l’applicazione e osservare il risultato visibile alla pagina swagger-ui.html. Sotto, lo screenshot della documentazione generata.
Utilizzare Swagger con Spring Security
Quando si accede alla pagina di documentazione Swagger UI, vengono caricati, attraverso chiamate HTTP, i file necessari alla creazione dell’interfaccia, come ad esempio il JSON api-docs.
Se stai utilizzando Spring Security, dovrai adottare delle accortezze per fare uso della pagina Swagger UI evitando errori di autenticazione. Se infatti hai configurato Spring Security come nell’esempio che trovi qui, allora, dovrai escludere dalla catena dei filtri di sicurezza le pagine che servono all’interfaccia Swagger: /v2/api-docs, /configuration/**, /swagger-resources/**, /swagger-ui.html, /webjars/**, /api-docs/**
@Override
public void configure(WebSecurity web) {
web.ignoring().antMatchers("/v2/api-docs", "/configuration/**", "/swagger-resources/**", "/swagger-ui.html", "/webjars/**", "/api-docs/**");
}Link di riferimento:
- GitHub del progetto demo: demo-api-service
- Articoli correlati: Creare Servizi Web RESTful con Spring Boot – Sicurezza delle API in Spring Boot
- Link esterni:
- Dipendenze springfox: swagger2 – swagger-ui
- Docs Springfox: Swagger docs
No comment yet, add your voice below!