Swagger: Documentare un Web Services Rest

Swagger è un progetto open source utilizzato per generare la documentazione per microservizi. Fornisce un’interfaccia utente per accedere ai nostri servizi web RESTful tramite browser. Per abilitare Swagger nell’applicazione Spring Boot, è necessario aggiungere le seguenti dipendenze nel pom.xml

<!-- SWAGGER 2 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>
		<dependency>h
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>

Creare una classe contraddistinta dall’annotazione @ EnableSwagger2:

@Configuration
@EnableSwagger2
@Api(value="mioprogetto", tags="controller di test che fa alcune operazioni bla bla")
public class SwaggerConfig 
{
	/*
	 * URL Swagger: http://localhost:9100/swagger-ui.html
	 * Docs: https://swagger.io/docs/
	 */

	@Bean
	public Docket api()
	{
		return new Docket(DocumentationType.SWAGGER_2)
				.select()
					.apis(RequestHandlerSelectors.basePackage("com.example.demo"))
					.paths(regex("/api/ciao.*"))
				.build()
				.apiInfo(apiInfo());
	}
	
	private ApiInfo apiInfo() 
	{
		return new ApiInfoBuilder()
				.title("ARTICOLI WEB SERVICE API")
                .description("Spring Boot REST API per la gestione articoli Prova")
                .version("1.0.0")
                .license("Apache License Version 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                .contact(new Contact("pinco pallino", "https://dgkdg.it", "pinuccio@gg.it"))
                .build();
	}
	
	
}

Analizziamo il codice:

@Bean
	public Docket api()
	{
		return new Docket(DocumentationType.SWAGGER_2)
				.select()
					.apis(RequestHandlerSelectors.basePackage("com.example.demo"))
					.paths(regex("/api/ciao.*"))
				.build()
				.apiInfo(apiInfo());
	}

Questo metodo specifica qual’é il package, e l’url, in cui si trovano i nostri servizi.

private ApiInfo apiInfo() 
	{
		return new ApiInfoBuilder()
				.title("ARTICOLI WEB SERVICE API")
                .description("Spring Boot REST API per la gestione articoli Prova")
                .version("1.0.0")
                .license("Apache License Version 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                .contact(new Contact("pinco pallino", "https://dgkdg.it", "pinuccio@gg.it"))
                .build();
	}

La classe ApiInfo contiene le informazioni generali dei nostri servizi.

In cima alla classe c’è l’annotation

@Api(value="mioprogetto", tags="controller di test che fa alcune operazioni bla bla")
public class SwaggerConfig 
{

Che ci fornisce informazioni di massima su cosa fa questo micro servizio. Questa info la vedremo in cima alla nostra documentazione.

Analizziamo ora il controller.

package com.example.demo;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.CrossOrigin;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

@RestController
@CrossOrigin(origins = "http://localhost:4200")
@Api(value = "HelloWorldSpringBootSwagger", tags = "Controller di prova ")
@RequestMapping("/api")
public class HelloController {

	@ApiModelProperty(notes = "codice del nostro articolo")
	private String codice;

	// ------------------- Ricerca Per Codice ------------------------------------
	@ApiOperation(value = "Ricerca articolo per codice", notes = "Restituisce i dati dell'articolo in formato JSON", response = String.class, produces = "application/json")
	@ApiResponses(value = { @ApiResponse(code = 200, message = "L'articolo cercato è stato trovato!"),
			@ApiResponse(code = 404, message = "L'articolo cercato NON è stato trovato!"),
			@ApiResponse(code = 403, message = "Non sei AUTORIZZATO ad accedere alle informazioni"),
			@ApiResponse(code = 401, message = "Non sei AUTENTICATO") })
	@RequestMapping(value = "/ciao", method = RequestMethod.GET, produces = "application/json")
	public ResponseEntity<String> helloWorld()

	{
		System.out.println("****** dentro *******");

		return new ResponseEntity<String>("ciao mamma", HttpStatus.OK);
	}
	
	// ------------------- Ricerca Per Codice ------------------------------------
	@ApiOperation(value = "Ricerca articolo per codice", notes = "Restituisce i dati dell'articolo in formato JSON", response = String.class, produces = "application/json")
	@ApiResponses(value = { @ApiResponse(code = 200, message = "L'articolo cercato è stato trovato!"),
			@ApiResponse(code = 404, message = "L'articolo cercato NON è stato trovato!"),
			@ApiResponse(code = 403, message = "Non sei AUTORIZZATO ad accedere alle informazioni"),
			@ApiResponse(code = 401, message = "Non sei AUTENTICATO") })
	@RequestMapping(value = "/ciaoDue", method = RequestMethod.GET, produces = "application/json")
	public ResponseEntity<String> helloWorld(@ApiParam("codice articolo") @PathVariable("codice") String codice)
	{
		System.out.println("****** dentro *******");

		return new ResponseEntity<String>("ciao mamma", HttpStatus.OK);
	}


}

Su ogni metodo aggiungiamo le seguenti annotation:

	// ------------------- Ricerca Per Codice ------------------------------------
	@ApiOperation(value = "Ricerca articolo per codice", notes = "Restituisce i dati dell'articolo in formato JSON", response = String.class, produces = "application/json")
	@ApiResponses(value = { @ApiResponse(code = 200, message = "L'articolo cercato è stato trovato!"),
			@ApiResponse(code = 404, message = "L'articolo cercato NON è stato trovato!"),
			@ApiResponse(code = 403, message = "Non sei AUTORIZZATO ad accedere alle informazioni"),
			@ApiResponse(code = 401, message = "Non sei AUTENTICATO") })
	@RequestMapping(value = "/ciao", method = RequestMethod.GET, produces = "application/json")
	public ResponseEntity<String> helloWorld()

che ci informano su cosa fa l’operazione, e i vari codici di risposta che possiamo ottenere.

Se il metodo ha in ingresso un parametro, lo possiamo documentare con  @ApiParam(“codice articolo”)

Esempio

// ------------------- Ricerca Per Codice ------------------------------------
	@ApiOperation(value = "Ricerca articolo per codice", notes = "Restituisce i dati dell'articolo in formato JSON", response = String.class, produces = "application/json")
	@ApiResponses(value = { @ApiResponse(code = 200, message = "L'articolo cercato è stato trovato!"),
			@ApiResponse(code = 404, message = "L'articolo cercato NON è stato trovato!"),
			@ApiResponse(code = 403, message = "Non sei AUTORIZZATO ad accedere alle informazioni"),
			@ApiResponse(code = 401, message = "Non sei AUTENTICATO") })
	@RequestMapping(value = "/ciaoDue", method = RequestMethod.GET, produces = "application/json")
	public ResponseEntity<String> helloWorld(@ApiParam("codice articolo") @PathVariable("codice") String codice)
	{
		System.out.println("****** dentro *******");

		return new ResponseEntity<String>("ciao mamma", HttpStatus.OK);
	}

Possiamo anche documentare, oltre ai controlller, anche ad esempio le classi model. Per fare questo usiamo l’annotation @ApiModelProperty

Esempio

public class Articolo {

//	@Id
//	@Column(name = "CODICE")
	@ApiModelProperty(notes = "Codice Articolo")
	private int codice;

	public int getCodice() {
		return codice;
	}

	public void setCodice(int codice) {
		this.codice = codice;
	}
	
	
	
}

Avviamo il servizio e vediamo ora che cosa otterremo con queste annotation.

Dal log notiamo

Mapped URL path [/v2/api-docs] onto method [springfox.documentation.swagger2.web.Swagger2Controller#getDocumentation(String, HttpServletRequest)]

Questo path (v2/api-docs) è quello che dobbiamo richiamare per ottenere la nostra documentazione in formato json

http://localhost:8080/v2/api-docs

Questo formato, anche se leggibile, non è comodo, ma swagger ci fornisce anche una interfaccia grafica consultabile da browser ad uno specifico indirizzo

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

Questa è la documentazione generata.

Notiamo che è presente anche l’elenco dei metodi generati

con tutte le info che abbiamo inserito

(Visited 93 times, 2 visits today)

Lascia un commento

Il tuo indirizzo email non sarà pubblicato. I campi obbligatori sono contrassegnati *