AKA Swagger
1. Introducción
Debido al auge de las APIs y las arquitecturas de microservicios experimentado en los últimos años también se ha producido un auge en las herramientas de definición, así como su estandarización.
OpenAPI es la principal de ellas, siendo actualmente el estándar de facto de la industria. No es la única, recordemos que existe RAML, pero es la más utilizada actualmente. Está disponible en las versiones 2 y 3, siendo la primera de ellas la más extendida hasta el momento.
2. Principios de definición de APIs REST
Autoconsumible
REST pragmático
Formatos de entrada / salida
Lo que sí debe evitarse es mezclar distintos formatos en una misma API, salvo que la naturaleza del recurso lo requiera. Por ejemplo, todos los endpoints de una API devuelven JSON, excepto uno que devuelve documentos PDF. Si es necesario devolver PDF se debe hacer. Lo que no se debe hacer es mezclar JSON, XML texto plano sin ningún tipo de organización o motivo justificado.
Los parámetros numéricos deben definirse preferiblemente como tales, no como cadenas de texto. Las fechas deben respetar un estándar, siendo ISO 8601 el recomendado.
Respuesta estándar
{
«result»: {
«status»: boolean,
«http_code»: integer,
«info»: «string»,
«errors»: [
{
«code»: integer,
«message»: «string»
}
]
},
«data»:{…}
}
URLs sencillas y recursos claros
También debemos procurar que los nombres de los recursos sean descriptivos de lo que devuelven. Se deben evitar nombres genéricos como resources, items, objects, etc. En el ejemplo anterior queda claro que se devuelven las cuentas de un cliente en concreto. A este respecto cabe destacar que se deben indicar correctamente las relaciones entre elementos. La estructura de la URL debe respetar el patrón /recurso/{identificador}/subrecurso/{identificador}
¿Verbos? Sólo HTTP, gracias
· GET /clientes/{id}/cuentas
· GET /clientes/cuentas/getAccountByCustomerId
Y encima el verbo está en inglés…
Un ejemplo REAL de recurso en una API de un cliente:
«GET /cfrcie9subclase2/search/findByFcBajaFilaIsNullAndId_cdcie9ClaseAndId_cdcie9SubclaseOrderByDsCie9Subclase2»
Da escalofríos sólo de verlo.
3. Documento de definición
Este hecho nos da la idea de que, a partir de una definición escrita en OpenAPI, podemos usar todo tipo de herramientas para realizar distintas tareas:
· Validar si la definición se ajusta al estándar OpenAPI
· Generar documentación
· Generar código
· Generar suites de pruebas
· Etc.
Estructura del documento de definición con swagger
Siempre se comienza con esta etiqueta, con valor ‘2.0’. De esta forma indicamos que se trata de un documento escrito siguiendo el estándar OpenAPI v2.
· info:
Este objeto contiene la siguiente información y otra no obligatoria pero no menos importante:
– Title: nombre de la API
– Version: versión de la API
– Description: no es obligatoria, pero como se ha dicho anteriormente hay que describir todo, aunque pequemos de pesados. Mejor ser pesados a que nos estén llamando constantemente para saber para qué sirve y cómo se consume la API.
· host:
Indica la máquina en la que se aloja la implementación de la API. Puede ser un nombre de dominio o una combinación máquina:puerto. Se debe excluir el protocolo, que viene indicado por otro elemento de OpenAPI.
· basepath:
Indica el contexto para construir la URL base de la API.
Este es el elemento que indica el protocolo. Se trata de un array en el
que podemos especificar HTTP, HTTPS o ambos. La URL base se compondrá como una combinación de este y los elementos anteriores: scheme + host + basepath.
Algún API manager (WSO2 AM) incluye también la versión en la URL base.
Si se especifican ambos protocolos se construyen dos URLs, una para cada uno.
· paths:
Esta es la sección que se usa para definir los endpoints, entendidos como recurso + método HTTP. Se debe definir todo:
– Ruta
– Descripción
– Parámetros de entrada (tipos, restricciones y ejemplos)
– Respuestas posibles (todas, así como ejemplos para todas ellas)
No vamos a entrar en detalles porque requiere una explicación mucho más larga de la que cabe en este documento. Enlazaremos la documentación de OpenAPI v2 para aquellos que deseen ampliar su conocimiento.
· definitions:
En esta sección podemos definir todos los modelos de objetos que vayamos a usar para entradas y salidas. Todo lo que definamos aquí es reutilizable. De igual forma que con la sección anterior remitimos a la documentación oficial de OpenAPI v2.
Aquí se definen los parámetros reutilizables para toda la API. Si no se van a reutilizar es preferible definirlos en la sección paths sólo en el endpoint al que pertenecen.
· responses:
De igual forma que con los parámetros se pueden definir respuestas reutilizables comunes a varios o todos los endpoints en esta sección.
· security:
En esta sección se define un array con los esquemas de autenticación soportados por la API. OpenAPI v2 soporta la definición de los esquemas Basic Authentication, API Key y cualquiera de los flujos Oauth2. Estos esquemas se pueden referenciar desde los endpoints en la sección paths.
· securityDefinitions:
En esta sección se definen los detalles de los esquemas de autenticación definidos en la sección anterior (tipo, método de entrada, URLs de autenticación y petición de token, etc).
4. Herramientas para definir APIs con swagger
· Editor online: Swagger.io
Permite editar y navegar por el documento. Presenta la definición en el lado izquierdo de la pantalla y la documentación generada en el lado derecho. A medida que se edita el documento la documentación cambia en caliente.
· Swaggerhub: Es una suite de pago que, aparte del editor, ofrece otros servicios como la generación de mock servers a partir de la definición, dominios para almacenar definiciones de elementos comunes entre distintas APIs o validación de estilo para mantener una misma línea entre todas las APIs de una organización.
· Visual Studio Code: Añadiendo tres plugins tenemos una herramienta bastante completa para editar, validar y generar la documentación de una API.
· IntelliJ Idea: Un conocido IDE Java que, con los plugins adecuados, ofrece la misma funcionalidad que VS Code.
· Otras: APIary, Apitive studio, RepreZen…
5. Utilidad para otros productos
Algunos ejemplos conocidos son los siguientes:
Publicación de la API en un API Gateway (WSO2)
Generación de código de cliente y de servidor (swagger codegen). En este aspecto cabe destacar la herramienta desarrollada en colaboración entre Cloudappi y Madrid Digital para generar el código de servidor a partir de una definición y una base de datos. Se genera un arquetipo en lenguaje Java con el framework Spring Boot.
Generación de documentación (Bump, openapi-viewer para VS Code)
Generación de test suites: Postman es capaz de generar automáticamente una suite de pruebas básica a partir de una definición OpenAPI.
En Cloudappi hemos desarrollado swagger2postman, que es una herramienta de generación de pruebas más completa. También se ha realizado en colaboración con Madrid Digital.
Mock servers: swaggerhub, postman y otras herramientas son capaces de levantar un servidor con una implementación estática a partir de una definición OpenAPI.
Blog realizado por David Marín
¡Habla con nuestros expertos!
