Documentación Avanzada de Apis Rest con Swagger

Swagger es un proyecto que permite diseñar, construir, documentar y utilizar servicios web RESTful. Hoy ejemplificamos cómo documentar nuestras APIS con anotaciones swagger:

1. Agregando Swagger a nuestra api.
2. Documentación básica.
3. Documentación avanzada.

Incluiremos Swagger en una aplicación construida con spring-boot y un servicio de ejemplo.

@RequestMapping("/api")
public class ExampleResource {

    @GetMapping("/examples")
    public ExampleDTO getExample() {
        ExampleDTO exampleDTO = new ExampleDTO();
        exampleDTO.setFirstAttribute("the first");
        exampleDTO.setLongAtribute(3L);
        return exampleDTO;
    }
    }

public class ExampleDTO implements Serializable {

    private String firstAttribute;
    private String secondAttribute;
    private Long longAtribute;
//... Getters and Setters
}

1. Agregando Swagger a nuestra api

Agregando dependencias

<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>

Habilitando Swagger en el proyecto

@SpringBootApplication
@EnableSwagger2
public class SwaggerDemoApplication {
}

Con las configuraciones anteriores ya está tenemos todo listo y podremos ver nuestra api con swagger-ui, accediendo a http://localhost:8080/swagger-ui.html

2. Documentación básica

Vamos a incluir una descripción de qué esperamos en la entrada y qué se obtendrá como resultado.

Desde la anotación @ApiOperation podemos describir el nombre de la operación (value), una descripción (notes). Permite además especificar la respuesta @ApiResponses y dentro de éstas el status http (code) y una descripción de éstos (message).

 @ApiOperation(value = "Acá nombramos la operación"
            ,notes = "Podemos incluir una descripción más detallada que será útil al cliente")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "OK. El recurso se obtiene correctamente", response = ExampleDTO.class ),
            @ApiResponse(code = 400, message = "Bad Request.Esta vez cambiamos el tipo de dato de la respuesta (String)", response = String.class),
            @ApiResponse(code = 500, message = "Error inesperado del sistema") })
    @GetMapping("/examples")
    public ResponseEntity<Object> getExample1() {
        ExampleDTO exampleDTO = new ExampleDTO();
        exampleDTO.setFirstAttribute("the first");
        exampleDTO.setLongAtribute(3L);
        return ResponseEntity.badRequest().body("Descripción de error 400");
    }

Veamos el resultado

3.1. Documentación avanzada

Por defecto, swagger ordena alfabéticamente los atributos, sin embargo, muchas veces necesitamos ordenarlos de una manera diferente. Para esto vamos a especificar la posición de cada uno de los atributos de ExampleDTO.class.

Antes

Añadiendo anotaciones en ExampleDTO

    @ApiModelProperty(position = 0)
    private String firstAttribute;

    @ApiModelProperty(position = 1)
    private String secondAttribute;

    @ApiModelProperty(position = 2)
    private Long longAtribute;

Después

3.2. Documentación avanzada 2

Es muy común querer ocultar al usuario algún atributo en la entrada y sí mostrarlo en la respuesta, ejemplo el id de una tabla. Esto se logra utilizando el atributo hidden de @ApiModelProperty. En el ejemplo siguiente especificar el campo «firstAttribute».

  @ApiModelProperty(hidden = true)
    private String firstAttribute;

    private String secondAttribute;

    private Long longAtribute;

En la imagen anterior podemos ver cómo el atributo «firstAttribute» no forma parte la petición y sí está presente en la respuesta.

Conclusiones

Swagger es una potente herramienta que brinda muchas ventajas para nuestras Apis RestFul ya que hoy en día no se concibe una Api sin documentación. Documentar Apis con Swagger es muy eficaz y está a nuestra disposición de una manera simple, lo que les dará, a las Apis, un mayor potencial.

El código fuente utilizado se encuentra disponible en mi repositorio público:

https://github.com/adriam-delgado/swagger-demo.git