Un tutorial paso a paso para definir APIs utilizando Swagger

1. Definición de APIs
con Swagger
JOAQUIN COPETE
JCOPETEG@GMAIL.COM

2. ¿Qué es Swagger?
 Lenguaje de definición agnóstico del lenguaje para APIs REST
 Comprensible tanto para personas como máquinas
 Que permita descubrir y entender las capacidades de un servicio
sin necesidad de acceder a código fuente, documentación,…
 Además Swagger proporciona un gran ecosistema de
herramientas:
 Interfaces de usuario
 Librerías de código
 Editor del lenguaje
jcopete.com

3. Definición básica de un API REST
 Los elementos mínimos que un API REST debe contemplar en
formato swagger son:
 Swagger: indica la versión, en adelante usaremos la más reciente
actualmente, la 2.0
 Info: indica información de metadatos de las APIs
 Title: Título del API
 Description: breve descripción del API
 Version: describe el número de versión del API
 Paths: registra los diferentes paths y operaciones de las APIs
jcopete.com

4. Definición básica de un API REST
jcopete.com

5. Especificando el formato de
respuesta
 Se utiliza el objeto “definitions” para definir los tipos de datos que
pueden ser consumidos o producidos por las operaciones.
 Para definir el tipo de datos “Error” definimos sus propiedades:
 codigo: entero en formato int32
 mensaje: cadena de caracteres
 campos: cadena de caracteres
 Para definir el tipo de datos “Producto” definimos sus propiedades:
 idProducto: cadena de caracteres
 descripcion: cadena de caracteres
 nombre: cadena de caracteres
 capacidad: cadena de caracteres
 imagen: cadena de caracteres
jcopete.com

6. Especificando el formato de
respuesta
jcopete.com

7. Definiendo los recursos del API
 Para definir los recursos del API usamos el objeto “path”,
anteriomente habíamos definido un “path” mínimo para los
productos.
 Extendemos el “path” mínimo con los siguientes atributos:
 tags: no es obligatorio, pero nos facilitará las búsquedas en el API.
 summary: un pequeño resumen de la función de esta operación.
 description: una descripción detallada de la operación.
 operationId: un nombre único, y amigable, de operación.
jcopete.com

8. Definiendo la respuesta del API
 Utilizamos el objeto responses de forma que queda definida la
respuesta de la operación
 responses: se compone de varios elementos (description, schema,
headers, examples), por simplicidad lo resumiremos en dos.
 description: descripción de la respuesta. (Obligatorio).
 schema: define la estructura de la respuesta. Puede ser un tipo básico, una
primitiva o un objeto definido en la sección “definitions” (visto antes).
En nuestro caso definiremos la respuesta para el recurso “productos” de forma que
utilice la definición creada anteriormente. También utilizaremos la definición de error
para devolver respuestas apropiadas en caso de fallo.
jcopete.com

9. Respuestas
jcopete.com

10. Definiendo los parámetros del API
 Utilizamos el objeto Parameters para definir los parámetros de
llamada al método; asumiremos que los parámetros se pasan en el
query-string.
 Cada uno de los parámetros se definen de la siguiente forma:
 name: nombre del parámetro (obligatorio)
 in: tipo de parámetro [ query, header, path, formData o body ]. (obligatorio).
En nuestro caso vamos a utilizar el tipo query.
 desciption: breve descripción del parámetro.
 required: determina si el parámetro es obligatorio. [ true, false ]
 En nuestro caso usaremos dos elementos más:
 type: tipo del parámetro (obligatorio si el tipo no es body).
 tormat: formato del tipo de datos definido antes.
jcopete.com

11. Parámetros
jcopete.com

12. Gracias
Joaquin copete
jcopeteg@gmail.com
jcopete.com