Esercitazioni di Spring Boot 5: documentiamo le API
Dopo aver creato le nostre API vediamo come documentarle opportunamente.
Bisogna sempre ragionare nell'ottica di un generico utente, diverso dallo sviluppatore, che deve disporre di tutte le informazioni necessarie per poter utilizzare il nostro prodotto.
Anche in questo caso non occorre affidarsi a soluzioni fai da te ma scegliere una di quelle già collaudate e ampiamente diffuse sul mercato.
Ci serviremo di Swagger, molto conosciuto e impiegato anche in ambito Enterprise.
Con pochissime righe di codice potremo disporre di una comoda interfaccia web attraverso cui consultare ed eseguire direttamente le nostre API.
Per prima cosa aggiungiamo le dipendenze richieste al pom.xml del progetto.
La prima serve ad includere Swagger
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
mentre l'altra è relativa all'interfaccia web.
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
Il secondo passo consiste nel creare una classe di configurazione che andremo a collocare in un opportuno package denominato net.emmecilab.players.config. Questo per mantenere sempre un ordine tra le diverse classi ed individuare al volo la loro tipologia.
Sono richieste due annotazioni: @Configuration per indicare a Spring che la classe rappresenta la configurazione di un qualche servizio e @EnableSwagger2 che non richiede ulteriori commenti.
E' presente un singolo metodo pubblico che restituisce un oggetto di tipo Docket. Il metodo è annotato con @Bean in modo che sia Spring ad istanziarlo e gestirlo. Da osservare che abbiamo specificato il package all'interno del quale sono presenti le API da documentare (i controllers).
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("net.emmecilab.players.controllers"))
.paths(PathSelectors.any())
.build();
}
Inoltre è presente un metodo privato che restituisce un oggetto di tipo ApiInfo con cui possiamo personalizzare la documentazione aggiungendo ad esempio la versione delle API, la licenza, l'email dell'autore e così via.
private ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfo(
"Players REST API",
"Players REST API Documentation",
"1.0",
"Terms of service",
"mcicolella@libero.it",
"GPL v2 Licence",
"http://www.gnu.org/licenses/old-licenses/gpl-2.0.html");
return apiInfo;
}
Ora non ci resta che vedere un esempio di annotazione da utilizzare con le API.
Posizioniamoci nella classe controller e in corrispondenza dell'endpoint "/players",che restituisce la lista dei calciatori, aggiungiamo il seguente codice
@ApiOperation(value = "View a list of players")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Successfully retrieved list")
,
@ApiResponse(code = 401, message = "You are not authorized to access this resource")
,
@ApiResponse(code = 404, message = "List not found")
})
In particolare l'annotazione @ApiOperation consente di associare una descrizione all'endpoint mentre con @ApiResponse possiamo personalizzare i messaggi restituiti in corrispondenza dei vari codici di stato di HTTP.
Un discorso simile vale per tutti gli altri endpoint.
A questo punto vediamo il risultato del nostro lavoro.
Dopo aver avviato l'applicazione, come già visto nelle precedenti esercitazioni, puntiamo il browser all'indirizzo http://localhost:8080/v2/api-docs e vedremo la documentazione prodotta da Swagger in formato JSON.
In alternativa possiamo visualizzare un'interfaccia grafica molto più accattivante e funzionale, in quanto è possibile testare uno per uno tutti gli endpoint, oltre ad avere pronte le stringhe da utilizzare da riga di comando, ad esempio con curl.
In questo caso l'indirizzo da digitare nel browser è http://localhost:8080/swagger-ui.html
Come sempre vi rimando al codice completo su GitHub.
Alla prossima!
[LINKS]
Soluzioni personalizzate per le vostre esigenze
