martes, 17 de septiembre de 2013

Turnapi: Documentar APIs en la nube

Llevo desde hace un tiempo trabajando en un proyecto entre varias empresas en el que una desarrolla una API con ciertas funcionalidades y otras consumen esta API desde sus aplicaciones. El caso es que, lógicamente, surgió la necesidad de documentar la API y tener esta documentación actualizada y accesible a todos los participantes... se pensó en Google Docs y otras soluciones similares pero finalmente optamos por Turnapi, os hago un breve resumen.

¿Qué es turnapi? Es una herramienta que nos permite de forma fácil e intuitiva documentar las APIs que desarrollemos. Dispone de control de versiones, es fácilmente configurable, podemos organizar la información, restringir el acceso a los usuarios que queramos, realizar búsquedas de forma global sobre toda la documentación... entre otras funcionalidades. La herramienta dispone de una versión gratuita 100% operativa aunque también dispone de versiones de pago que ofrece opciones como uso de nuestro dominio, SSL,... a través de este enlace podéis acceder a la lista de planes y precios de turnapi.

A continuación os comentaré los primeros pasos a dar en Turnapi y cómo llevar a cabo algunos aspectos de configuración:

  • Lo primero que debemos hacer es registrarnos, podemos hacerlo desde la home de la web de Turnapi indicando nombre, mail, contraseña y dominio (se creará un subdominio del tipo dominioespecficado.turnapi.com, por ejemplo, test.turnapi.com).


  • Una vez registrados en Turnapi accedemos a la página principal de la documentación de la API. Podemos configurar logo y menú de la cabecera, configurar el tree de la izquierda añadiendo nuevas entradas o modificar el contenido de la página que se nos visualiza (con título References). En la parte inferior de la pantalla hay disponible otro menú que nos permite cambiar el modo de visualización, seleccionar temas, acceso a la gestión de usuarios,...


  • Tal como comentaba en el apartado anterior,si en el menú inferior pulsamos sobre la opción 'Themes' podremos escoger el estilo para la documentación de nuestra API.


  • Si pulsamos sobre la opción 'Configure header' podremos cambiar el logo de la documentación de nuestra API, modificar los títulos de los menús existentes y añadir/elminar menús (de la barra superior horizontal).


  • En el cuadro de texto central escribiremos el contenido de la página pudiendo usar texto normal, tags html, listas, negrita, cursiva, imágenes,... y también añadir métodos (prefijo '#') y parámetros (prefijo '@param').


    La visualización de la página anterior sería la siguiente; en la parte inferior de la documentación nos saldrán links para exportarla a HTML, PDF o imprimir:


  • Pulsando sobre 'Configure tree' añadiremos nodos en el menú de la izquierda; dentro del mismo podemos crear submenús lo que nos permitirá organizar mejor la documentación de nuestra API.


  • En cualquier momento podemos grabar o grabar y publicar nuestra documentación. En cuanto grabemos se actualizarán las revisiones correspondientes (guardadas o guardas y publicadas y pulsando sobre 'history' veremos el historial de cambios.


  • Pulsando en la opción 'Settings' del menú inferior podremos indicar nombre y copyright para nuestro proyecto de documentación y lo que es más importante, hacer este proyecto privado; si lo marcamos supondrá que sólo podrá acceder a la documentación de la API aquellos usuarios que invitemos. MUY IMPORTANTE, por defecto los proyectos no son privados así que si no marcamos esta característica nuestra documentación será accesible a cualquier usuario de internet.


  • Si vamos a la opción 'Users' del menú inferior veremos la lista de usuarios del proyecto (aquellos que tienen acceso a la documentación si el proyecto es privado).


  • Podemos añadir usuarios pulsando el botón 'Invite Person' o eliminarlos pulsando sobre el link 'Remove' (y yo me pregunto, ¿por qué no habrán hecho 2 botones o 2 links?. Al invitar a una persona nos pide su mail y a este le llega el link de acceso y su contraseña (autogenerada), el login es su correo.


  • ... y cómo las características anteriores podría mostraros varias más. Podéis acceder al blog de la herramienta para ver otras características o acceder al libro de ruta para ver las últimas mejoras implementadas.

Hasta aquí el artículo de hoy, ¿qué os ha parecido? Si no os convence Turnapi como herramienta para generar la documentación de nuestras APIs existen otras herramientas similares como Apiary, Dojo... Recordad que dentro de areaTIC podéis encontrar otros artículos interesantes, no dudéis en consultar nuestro archivo, también podéis seguirnos por RSS o las principales redes sociales (twitter, facebook, linkedin...).


No hay comentarios:

Publicar un comentario