Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Definición de APIs
con Swagger
JOAQUIN COPETE
JCOPETEG@GMAIL.COM
¿Qué es Swagger?
 Lenguaje de definición agnóstico del lenguaje para APIs REST
 Comprensible tanto para personas como má...
Definición básica de un API REST
 Los elementos mínimos que un API REST debe contemplar en
formato swagger son:
 Swagger...
Definición básica de un API REST
jcopete.com
Especificando el formato de
respuesta
 Se utiliza el objeto “definitions” para definir los tipos de datos que
pueden ser ...
Especificando el formato de
respuesta
jcopete.com
Definiendo los recursos del API
 Para definir los recursos del API usamos el objeto “path”,
anteriomente habíamos definid...
Definiendo la respuesta del API
 Utilizamos el objeto responses de forma que queda definida la
respuesta de la operación
...
Respuestas
jcopete.com
Definiendo los parámetros del API
 Utilizamos el objeto Parameters para definir los parámetros de
llamada al método; asum...
Parámetros
jcopete.com
Gracias
Joaquin copete
jcopeteg@gmail.com
jcopete.com
Upcoming SlideShare
Loading in …5
×

Definición de apis con swagger

Un tutorial paso a paso para definir APIs utilizando Swagger

Definición de apis con swagger

  1. 1. Definición de APIs con Swagger JOAQUIN COPETE JCOPETEG@GMAIL.COM
  2. 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. 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. 4. Definición básica de un API REST jcopete.com
  5. 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. 6. Especificando el formato de respuesta jcopete.com
  7. 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. 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. 9. Respuestas jcopete.com
  10. 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. 11. Parámetros jcopete.com
  12. 12. Gracias Joaquin copete jcopeteg@gmail.com jcopete.com

×