Introducción

Swagger es un estándar de definición y documentación de API's.


Swagger is an open source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful Web services. While most users identify Swagger by the Swagger UI tool, the Swagger toolset includes support for automated documentation, code generation, and test case generation.


Es decir, es un estándar de facto, adoptado por toda la comunidad de desarrolladores, que te permite utilizar herramientas de diseño, documentación y testing de una forma sencilla, ahorrando mucho trabajo y clarificando de una forma muy visual cómo se comporta tu producto.


El resultado de aplicar este estándar es un fichero JSON con una estructura específica que, con las herramientas adecuadas, facilita opciones y acciones tales como generar automáticamente un proyecto de cliente de consumo de la API en uno de los muchos lenguajes de programación soportados por el estándar.


PROFUNDIZA: Swagger es lo suficientemente complejo como para perderse un buen tiempo buceando por todas sus posibilidades, si tienes tiempo ni lo dudes, vale la pena.


Ayuda

Swagger es, al fin y al cabo, un fichero JSON (swagger.json) de definición de la API.


Para construir este fichero de forma dinámica, se han creado una serie de tablas en SQL que sirven de apoyo al proceso de ayuda.

  • Tabla que contiene los datos necesarios para crear la ayuda swagger de los datos incluidos en la tabla de procedimientos, es decir, de los procesos.
  • Tabla que contiene los datos necesarios para crear la ayuda de los parámetros de entrada y salida de los procesos. 
  • Tabla que contiene los datos necesarios para crear la ayuda swagger de las vistas contenidas en la tabla de vistas.


Para crear esta ayuda debemos tener en cuenta un par de consideraciones previas.


Por un lado, existe un procedimiento almacenado que rellena estas tablas, es decir, el paso lógico tras incluir cualquier nuevo registro en las tablas funcionales, es lanzar este proceso para poder tener acceso a la definición desde la interfaz swagger.


Por otro lado, el proceso que rellena estas tablas de ayuda se basa en los encabezados descriptivos de los procedimientos almacenados y vistas, lo cual supone una exigencia adicional para alcanzar un mínimo de calidad documental en los propios objetos de la base de datos.


Ejemplo de documentación de procedimiento almacenado. 
-- =============================================
-- #AUTHOR:
--              WSCodeIT
-- #NAME:
---             pTPV_Inicializar
-- #CREATION:
--              31/07/2018
-- #CLASIFICATION:
--              000-SISTEMA
-- #DESCRIPTION:
--              Inicializa el TPV
-- #PARAMETERS:
--              @IdCaja: Id de la caja de la TPV que se quiere los valores
--              @oXML:   fichero XML que devuelve toda la estructura inicial del entorno
-- #OBSERVATIONS:
--             
-- #CHANGES:
--         
-- #EXAMPLE:
--              DECLARE @oXML XML
--              EXEC pTPV_Inicializar @IdCaja = 1, @oXML = @oXML OUTPUT
--              SELECT @oXML
-- =============================================



IMPORTANTE: El procedimiento de creación de la ayuda (que no nombramos por seguridad), una vez procesados todos los registros de las tablas de la API, devuelve una lista con los elementos sobre los que no se ha podido generar ayuda. Es recomendable corregir estos procesos y volver a lanzar la ejecución del procedimiento para tener completamente mapeados todos los elementos en el fichero Swagger.




Ahora API Swagger

Una vez clarificados los conceptos anteriores, es momento de introducirse en el maravilloso mundo de la interfaz de acceso a la API de Swagger.




La interfaz, accesible desde la propia URL de la API (http://URL:PUERTO/api), muestra un lista por cada uno de los controladores definidos.


Un controlador no es más que un grupo de acciones contenidos dentro de un mismo marco lógico encargados de recibir y procesar las solicitudes a la API.


La API, actualmente, tiene cinco controladores básicos:

  • External: controlador cargado a partir de una librería externa, que puede ser desarrollada por terceros, para añadir funcionalidad adicional.
  • Token: controlador para la gestión del proceso de autenticación y obtención del Token JWT.
  • Utils: controlador para utilidades adicionales que se escapan del marco de ejecución propio de la API basada en procedimientos almacenados y consultas a vistas.
  • EXEC: controlador que carga todos los procedimientos almacenados de la tabla de procesos.
  • List: controlador que carga todas las vistas de la tabla de vistas.


Si entramos en un elemento del listado vemos la enorme potencialidad de esta herramienta de trabajo.



De un simple vistazo vemos 

  • El método de la llamada HTTP para acceder al elemento: PUT (POST, GET, DELTE)
  • La URL de acceso al método: /api/Process/pTPV_Inicializar
  • Una descripción del método: inicializa el TPV
  • Los parámetros que espera el procedimiento almacenado: IdCaja y oXML
  • El tipo de datos de entrada y salida en Parameter content type y Respone content type: application/json
  • Los tipos de respuesta que puede devolver, con su código http asociado y una muestra del posible valor: 200 con la devolución de un JSON y 401 en caso de no estar autorizado.


Además, si accedemos a la ficha de modelo, situada justo en la parte superior del ejemplo de datos esperados, veremos la definición de los campos con sus tipos y una descripción de los mismos. Datos sacados del encabezado descriptivo de los procedimientos almacenados y vistas, de ahí la importancia de cuidar la documentación específica de cada objeto de la base de datos.



Es más, desde el propio elemento, haciendo uso del botón situado en la parte superior derecha "Try it out", entraremos en modo edición para rellenar los campos esperados por la acción y poder ejecutar una llamada sin necesidad de utilizar herramientas externas tipo Postman.



No obstante, y puesto que la seguridad debe respetarse también en este entorno de pruebas, será necesario realizar a mano el procese de autenticación, obtención del Token, y autorización en el propio Swagger.


Prueba en Swagger

Como se ha comentado, para poder ejecutar los procesos directamente en la interfaz de Swagger, es necesario respetar los criterios de autenticación, es decir, incluir el Token en cada llamada.


Afortunadamente  también se puede realizar desde la propia interfaz.


Para ello, primero debemos acceder al controlador Token, utilizar el botón Try it Out, poner nuestros datos de acceso (usuario y password de la base de datos), y darle a Execute.




La ejecución, en caso de que la validación de usuario y contraseña sean correctos, devuelve un JWT Token que deberemos incluir en cada una de las llamadas posteriores para no recibir un error de autorización.



El siguiente paso es copiar este Token en introducirlo en la pantalla de autorización del propio Swagger, a la cual se accede desde el botón Authorize situado en la parte superior derecha de la interfaz.



Puesto que es un Bearer Token es necesario incluir la palabra "Bearer" antes del propio token.


Una vez realizado este paso, ya estamos en disposición de consumir cualquier método de la API desde la propia interfaz de Swagger sin necesidad de programar un cliente o utilizar herramientas de terceros.