Definición de apis con swagger
12
Transcript of Definición de apis con swagger
Definición de APIs con SwaggerJOAQUIN [email protected]
¿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
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
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
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
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
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
