Documentación Avanzada de Apis Rest con Swagger

2
14343
plumaje pavo real

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.

1. Agregando Swagger a nuestra api

Agregando dependencias

Habilitando Swagger en el proyecto

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

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

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

 

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

2 Comentarios

Dejar respuesta

Please enter your comment!
Please enter your name here