Swagger es una herramienta que nos permite documentar de una forma sencilla nuestras APIs REST hoy por hoy se ha convertido en uno de los standares de facto a la hora de trabajar . Cada día publicamos un mayor número de APIs REST y lo lógico es que publiquemos una documentación clara de como trabajar con ellas. Swagger nos permite hacerlo de una forma muy rápida y directa.
Vamos a ver un ejemplo, para ello partiremos de un proyecto de Spring boot que tiene un servicio que devuelve una lista de personas. Las dependencias de Maven son:
<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency> </dependencies>
Spring @RestController
En ellas podemos ver como hemos incluido las nuevas librerías. El siguiente paso es definir un servicio REST con la anotación @RestController.
package com.arquitecturajava.rest; import java.util.ArrayList; import java.util.List; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class ControladorPersona { @GetMapping("/personas") public List&amp;lt;Persona&amp;gt; findAll() { List&lt;Persona&gt; lista= new ArrayLis&lt;Persona&gt;(); lista.add(new Persona("pepe","perez",25)); lista.add(new Persona("juan","sanchez",35)); lista.add(new Persona("ana","gomez",25)); return lista; } }
Configuración de Spring
Es momento de configurar la herramienta para que nos genere una documentación del API REST.Para ello añadimos un nuevo fichero de configuración de Spring.
package com.arquitecturajava.rest1; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; import static springfox.documentation.builders.PathSelectors.regex; @Configuration @EnableSwagger2 public class SwaggerConfiguration { @Bean public Docket productApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.arquitecturajava.rest")) .paths(regex("/personas.*")) .build(); } }
Aquí configuramos swagger para que publique documentación para la url que publicamos en este caso nuestra url de /personas. Nos queda por ver el fichero de configuración principal de Spring framework que importará el de Swagger.
package com.arquitecturajava.rest; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.annotation.Import; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; @SpringBootApplication @Import(SwaggerConfiguration.class) public class RestApplication implements WebMvcConfigurer{ public static void main(String[] args) { SpringApplication.run(RestApplication.class, args); } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); } }
Swagger y documentación
Arrancamos la aplicación con Spring Boot y accederemos de forma directa a la url de personas que nos mostrará la lista de personas.
Hasta aquí todo es lo habitual , sin embargo si miramos los ficheros de log de Spring boot podremos ver que se han publicado más urls.
Dos de las urls más importantes de swagger son /v2/api-docs que publica la documentación en formato json . Si echamos un vistazo a la url recibiremos algo como :
En principio es una información que nos puede parecer extraña. Es suficiente abrirla con un visor de JSON para que la información nos quede mucho más clara:
Podemos ver claramente la definición de la operación y el tipo de objeto que devuelve, así como información adicional. Otra de las opciones que tenemos es acceder a una vista web de la documentación mucho más amable utilizando la url /swagger-ui.html.
Entramos a controlador persona y vemos los métodos que tiene soportados:
Acabamos de documentar nuestro api REST con swagger.
Otros artículos relacionados:
Hola buen día, muy bueno tu blog, duda sobre swagger, al parecer hay un problema cuando declaro dentro de la misma clase un objeto de la clase, swagger no lo interpreta y me aparece vació, que podría ser??
Clase en Java:
public class AudienceType {
private Long idAudienceType;
@Length(max = 255)
private String name;
private AudienceType parentAudienceType; <—– en swagger aparece vació en el modelo
}
Modelo en swagger:
[
AudienceType{
idAudienceType integer($int64)
name string
parentAudienceType {} <——- aqui es el problema en swagger
}]
muchas gracias.
que el campo es privado probablemente tiene un get/set publicos?
Buen día,
gracias por su pronta respuesta.
ya intente colocando el campo en publico y sigue igual en swagger.
public AudienceType parentAudienceType; <—– en swagger aparece vació en el modelo
Buen día,
Gracias por su pronta respuesta,
coloque el campo en public y no funcionó,
public AudienceType parentAudienceType; <—– en swagger aparece vació en el modelo
Lo primero felicitarte por el blog, me parece de muy buena calidad. Preguntar sobre los rest si es correcto diseñarlos q devuelven , Esto lo hago porque controlo las excepciones y en caso de que surjan devuelvo otro objeto con la info de la exception en vez del objeto esperando. Swagger sigue sirviendo en este ejemplo o es mal diseño?
Lo mejor es devolver un mensaje de error http y adjuntar en un response entity la trazabilidad que quieras
Hola, tienes algún ejemplo de como se regresan los estados HTTP.
ahora mismo no 🙁
No se si te sirva, esto seria el controller.
@PostMapping(“/save”)
public HttpEntity save(@Valid @RequestBody ProductRequest productRequest)
throws ValidationExceptions {
validateCreateRequest(productRequest);
return new ResponseEntity(productService.saveProduct(productRequest), HttpStatus.OK);
}
en tu implementacion:
throw new ValidationExceptions(“0108”, “Tipo no valido: ” + productRequest.getType().toUpperCase(),
HttpStatus.OK);
y la clase ValidationExceptions
public class ValidationExceptions extends Exception {
private HttpStatus status;
private String codError;
public ValidationExceptions(String codError, String message, HttpStatus status){
super(message);
this.status = status;
this.codError = codError;
}
ojala te sirva..!! saludos..
gracias 🙂
Hola estoy en un context de un proyecto dinámico. Con payara y glassfish. Cómo puedo incluir swagger?
No lo he probado ,ya lo siento echa un veo aquí
Hola, si quiero utilizarlo sin Spring Boot ? en una aplicacion Spring MVC? Gracias
Casi seguro que tendras que usar un Webinitializer y configurar spring con anotaciones
uso de configuration
Muy util gracias
de nada 🙂
Gracias por la info
de nada 🙂