SwaggerComo ya sabréis, Apicultur está construida a partir de API Manager, la solución Open Source completa para gestión, monitorización y publicación de APIs de WSO2. [Nosotros coloquialmente la llamamos Hueso ;-)] Esta solución middleware dispone de una aplicación web completa, que permite a los desarrolladores encontrar, entender y suscribirse a las APIS previamente publicados de una manera segura y con el nivel de servicio que se estime oportuno, tanto desde la parte cliente como desde la parte proveedora del servicio.

En el momento de publicar una API, la aplicación permite facilitar a los desarrolladores que la vayan a utilizar, la URL asociada al WSDL y al WADL del servicio publicado, pero hay que reconocer que la documentación proporcionada por estos archivos no es la más fácil de entender ni visualizar. Actualmente, están surgiendo diversas iniciativas para la descripción, documentación y visualización de servicios RESTful. Para nosotros, entre todos ellos, destaca Swagger por la versatilidad, facilidad de uso y estética del cliente web que tiene incorporado, y sobre todo porque permite testear el API desde la propia página web, permitiendo que el usuario se haga una idea rápida de la API, antes de ponerse a leer toda la documentación. Algo así como “prueba mi comida y si te gusta te cuento la receta”.

Swagger, permite generar automáticamente los archivos necesarios para que su cliente web pueda mostrar la documentación asociada al servicio (verbos permitidos, urls, parámetros, tipos, descripciones, etc.), pero requiere la introducción de código y etiquetados adicionales en tiempo de desarrollo. Aquí os dejamos unos enlaces por si queréis profundizar en la solución. Lamentablemente, si posteriormente nuestros servicios web son publicados a través del API Manager, la documentación generada en tiempo de desarrollo no será la adecuada al nuevo entorno de producción, debido principalmente, a la diferencia de EndPoints entre el API desarrollado y el publicado. Por tanto, si queremos beneficiarnos del cliente web de Swagger en nuestra Store de API Manager tendremos que optar por utilizar únicamente la parte UI de Swagger y generar nosotros mismos los documentos asociados a cada una de los APIS publicados.

Ejemplo de integración de Swagger en Apicultur (Api Manager)

Ejemplo de integración de Swagger en Apicultur (Api Manager)

 

Esto, que a priori parece complicado, es muy sencillo y aquí os explicamos como hacerlo, paso a paso.

Descargar el entorno UI de Swagger

Procederemos a la descarga de todo el cliente web de Swagger, que consiste básicamente en un conjunto de html, js y css.

Publicación del cliente en el API Store

Ahora que disponemos de los archivos, procederemos a su ubicación en la API Store, para ello, accederemos a la ubicación

<AM_HOME>/repository/deployment/server/jaggeryapps/store/site/themes/fancy/templetes

y creamos una nueva carpeta denominada “swagger”, donde ubicaremos los archivos anteriormente descargados.

En nuestra solución, hemos optado por mostrar la documentación en formato Swagger en la misma página de información de la API, más en concreto, en la pestaña Overview. Localizamos el template encargado de mostrar esa pestaña.

<AM_HOME>/repository/deployment/server/jaggeryapps/store/site/themes/fancy/templetes/api/overview/templete.jag

En ella añadimos, en el espacio que nos interese mostrar la documentación, las siguientes capas HTML que son las que utilizará Swagger para cargar el contenido de la documentación:

<div id=”message-bar”>&nbsp;</div><div id=”swagger-ui-container”>

Si nuestra API Store funciona con protocolo http y https, será necesario también crear una nueva variable en el template.jag, denominada “discoveryUrl” y en ella almacenar el siguiente valor en función del protocolo utilizado:

<%
var discoveryUrl;
if (request.isSecure()){
discoveryUrl = jagg.getMappedUrl("/site/pages/api-docs/"+ api.name + "-" + api.version +"/api-docs.json");
}else{
discoveryUrl = jagg.getMappedUrl("/site/pages/api-doc/"+ api.name + "-" + api.version +"/api-docs.json");
}
%>
Posteriormente describiremos la utilidad de esta variable. Ahora, para incluir todos los js y css necesarios para el correcto funcionamiento accedemos al “inicializador” de la página Overview:

<AM_HOME>/repository/deployment/server/jaggeryapps/store/site/themes/fancy/templetes/api/overview/initializer.jag

Y en él, incluimos todos los js y css necesarios:

jagg.addHeaderJS("api/api-info", "api-info1", "templates/swagger/lib/jquery-1.8.0.min.js");
jagg.addHeaderJS("api/api-info", "api-info2", "templates/swagger/lib/jquery.slideto.min.js");
jagg.addHeaderJS("api/api-info", "api-info3", "templates/swagger/lib/jquery.wiggle.min.js");
jagg.addHeaderJS("api/api-info", "api-info4", "templates/swagger/lib/jquery.ba-bbq.min.js");
jagg.addHeaderJS("api/api-info", "api-info5", "templates/swagger/lib/handlebars-1.0.rc.1.js");
jagg.addHeaderJS("api/api-info", "api-info6", "templates/swagger/lib/underscore-min.js");
jagg.addHeaderJS("api/api-info", "api-info7", "templates/swagger/lib/backbone-min.js");
jagg.addHeaderJS("api/api-info", "api-info8", "templates/swagger/lib/swagger.js");
jagg.addHeaderJS("api/api-info", "api-info9", "templates/swagger/swagger-ui.js");
jagg.addHeaderCSS("api/api-info", "api-info10", "templates/swagger/css/screen.css");
jagg.addHeaderCSSCode("api/api-info", "api-info11", ".swagger-ui-wrap {max-width: 960px;margin-left: auto;margin-right: auto;}.icon-btn {cursor: pointer;}#message-bar {min-height: 30px;text-align: center;padding-top: 10px;}.message-success {color: #89BF04;}.message-fail {color: #cc0000;}");

Adicionalmente, debemos incorporar un js que crearemos nosotros manualmente. Este archivo js, debe contener la función que se ejecutará una vez cargada la página y que se encarga de renderizar todo el código html necesario para mostrar la documentación de manera atractiva:

<script type=”text/javascript”>

$(function () {
window.swaggerUi = new SwaggerUi({
discoveryUrl:”<%=discoveryUrl%>”,
dom_id:”swagger-ui-container”,
supportHeaderParams: true,
supportedSubmitMethods: [‘get’, ‘post’, ‘put’],
onComplete: function(swaggerApi, swaggerUi){
if(console) {
console.log(“Loaded SwaggerUI”)
console.log(swaggerApi);
console.log(swaggerUi);
}
},
onFailure: function(data) {
if(console) {
console.log(“Unable to Load SwaggerUI”);
console.log(data);
}
},
docExpansion: “none”
});
window.swaggerUi.load();
});
</script>

Destacaremos en esta función los siguientes valores y atributos modificados respecto al contenido “de serie” que trae Swagger:

supportHeaderParams: Cambiamos este atributo a “true” para permitir a Swagger enviar nuestro token de aplicación en Api Manager y así poder utilizar las funcionalidades que permiten, además de mostrar la documentación, probar el resultado devuelto por la API.
discoveryUrl: Contiene la url del archivo JSON que contiene la información de la documentación a mostrar en el cliente Swagger.
headers: Aquí añadiremos nuestro token de aplicación, en el caso de que queramos, además de mostrar la documentación, permitir a los usuarios probarlas en directo.

Generación de documentación por cada API

Para disponer rápida y fácilmente de documentación para cada API publicada sin acceder al código interno de la aplicación Store de API Manager, basta con realizar los siguientes pasos:

Crear direcctorios para almacenar la docuementación de los servicios

Dentro de la carpeta

<AM_HOME>/repository/deployment/server/jaggeryapps/store/site/pages

crearemos dos nuevas subcarpetas denominadas “api-docs” y “api-doc”, donde se irán a buscar los archivos de documentación de cada API en función del protocolo de navegación que se esté utilizando (http, https). El contenido de estas dos carpetas será idéntico, lo cual facilita su mantenimiento y gestión. Sólo hay dos pequeños detalles a tener en cuenta para el correcto funcionamiento de la solución y que se explicarán en pasos ulteriores.

Crear direcctorio para cada API

Por cada API que queramos documentar crearemos en el directorio “api-docs” una subcarpeta denominada “NombreApi-Version”. Por ejemplo, si en mi API Store tengo una API denominada “OperacionesBasicas” y su versión es la “1.0”, la carpeta a crear se denominará “OperacionesBasicas-1.0”.
Dentro de este directorio, ubicaremos los archivos necesarios:
api-docs.json: Es el archivo principal y contiene enlaces a los archivos de las diferentes URL que permite el API y que son descritos en los archivos enlazados
archivoapi: Contiene la documentación de los métodos permitidos en la url, parámetros de entrada, tipo, descripciones, etc de cada uno los métodos permitidos.

Por ejemplo, para nuestro API “OperacionesBasicas” tendríamos el siguiente archivo api-docs.json:

{
"apiVersion":"1.0",
"swaggerVersion":"1.1",
"basePath":"https://mistoreapimanager:9443/site/pages/",
"apis":[
{
"path":"/api-docs/OperacionesBasicas-1.0/sumar",
"description":"Suma dos cantidades"
},
{
"path":"/api-docs/OperacionesBasicas-1.0/restar",
"description":"Resta dos numeros"
}
]
}

Como tengo 2 url diferenentes para mi API, tendré dos archivos para describir cada una de ellas “sumar” y “restar”. Mostramos como ejemplo el contenido de “sumar”, el otro archivo sería análogo. Para más referencias sobre el contenido de estos archivos se puede consultar API Declaration, Resource Listing, Parameters y Data Types .

Archivo “sumar”:


{
"apiVersion":"1.0",
"swaggerVersion":"1.1",
"basePath":"https://mistoreapimanager:9443",
"resourcePath":"operacionesbasicas/1.0/sumar",
"apis":[
{
"path":"operacionesbasicas/1.0/sumar/{sumando1}/{sumando2}",
"description":"Operationes de suma ",
"operations":[
{
"httpMethod":"GET",
"summary":"Suma dos cantidades pasadas por parámetro",
"notes":"Devuelve la suma de las cantidades pasadas por parámetro",
"responseClass":"Resultado",
"nickname":"getSuma",
"parameters":[
{
"name":"sumando1",
"description":"Primera cantidad a sumar",
"paramType":"path",
"required":true,
"allowMultiple":false,
"dataType":"long"
},
{
"name":"sumando2",
"description":"Segunda cantidad a sumar",
"paramType":"path",
"required":true,
"allowMultiple":false,
"dataType":"long"
}
],
"errorResponses":[
{
"code":401,
"reason":"No autorizado"
}
]
}
]
}
],
"models":{
"Resultado":{
"id":"Resultado",
"properties":{
"resultado":{
"type":"long"
}
}
}
}
}

Crear la copia de cada API para el otro protocolo

Una vez finalizada la documentación de nuestra API para el protocolo https, podemos copiar la carpeta completa en el directorio “api-doc” anteriormente creado y cambiar el contenido de los archivos del mismo, sustituyendo en las url el protocolo (y puerto si procede) https por el http. También será necesario cambiar las rutas , donde pusiera “/api-docs/” por “/api-doc/”.
“Y con esto y un bizcocho hasta mañana a las 8”. Si lo queréis ver en funcionamiento, aquí tenéis un ejemplo.

Tagged with →  
Share →