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