<Web> NubeAndo.COM </Web>

"Consultoría Informática en Desarrollo e Innovación Tecnológica"

Servicio Técnico Especializado

Seguridad Informática

Portales y Sistemas web para Negocios

Talleres de Capacitación

Especialista en Educación Superior

Desarrollo de Software de Escritorio y Movil

Marketing Digital en Redes Sociales

Docencia Universitaria y Técnica


"Educar es Compartir"

Generar documentacion de una API con apiDocjs

La documentación del código fuente forma parte fundamental de cualquier proyecto de desarrollo y más aun cuando trabajamos de forma colaborativa, integramos un gran grupo de programadores o desarrollamos alguna aplicación de acceso público.
Es necesario que cualquier otra persona pueda entender el código y saber para qué sirve cada una de las funciones, métodos o procedimientos empleados.
Los estándares de documentación pueden variar dependiendo del tipo de lenguaje en el que se esté trabajando, lo importante es ofrecer de forma simple y clara una explicación del uso de cada función.
Tradicionalmente desde el ambiente de desarrollo, la documentación se realiza en pequeños bloques de código comentado (o código que se escribe dentro de etiquetas de escape invisibles al compilador o intérprete). Por ejemplo en php podemos hacer lo siguiente :

/*
*  save some data
* param string id
* return true
*/
public function save($id){
return true;
}
Esta es una buen práctica, pero ocurre un problema al momento de compartir esta documentación con personas que no van a tener acceso al código fuente pero aun así van a hacer uso de la aplicación, como en el caso de una API, y es un poco tedioso el proceso de crear una página web donde escribir de una forma más entendible dicha documentación.
Afortunadamente tenemos a nuestra disposición muchas herramientas que pueden hacer este trabajo por nosotros y una de ellas es Apidocjs.

Como funciona ?

Apidoc (http://apidocjs.com/) lee todos los archivos dentro de un directorio, identifica la estructura de los comentarios y genera una página web en formato html de forma automática que contiene toda la documentación que hemos definido en nuestro código fuente.

Instalación

Desde la consola de comandos
sudo apt-get install nodejs-legacy
sudo apt-get install npm
sudo npm install apidoc -g

Documentación en php

Apidoc hace uso de algunas etiquetas que permiten identificar diversos elementos en la documentacion, como variables, respuestas, tipos de peticion, etc. que deberemos incluir para que puedan ser identificadas en orden de genearar el documento html correspondiente. En http://apidocjs.com/ podemos ver todas las etiquetas disponibles.
Este es un ejemplo de uso para comentar una petición de tipo get.
/**
* @api {get} /user/{id}
* @apiGroup User
* @apiDescription get data from a selected user.
* @apiPermission none
*
*
* @apiParam {Int} user id.
*

* @apiError 404 Validation <code>data</code> not found.
* @apiErrorExample {json} Error-Response:
* HTTP/1.1 404 Not found
* [
* { “data” : “Not found” }
* ]
*
* @apiSuccess (200) {json} success true.
* @apiSuccessExample {json} Success-Response:
* HTTP/1.1 200 OK
* {
* “success”: “true”,
* “data”: { collection }
* }
*/
Generando documentación en html
Es importante aclarar que los comentarios deben contar con la estructura que se ejemplificaba anteriormente. Necesitamos crear una carpeta que contenga los archivos que se van a generar.
mkdir apidoc
Ahora tan solo debemos ejecutar un comando para obtener el resultado que deseamos.
apidoc -i myapp/ -o apidoc/ -t mytemplate/
myapp/ sera el directorio que contiene el código a documentar.
apidoc/ es el directorio que acabamos de crear
mytemplate/ es opcional y lo podemos usar en caso de que desarrollemos nuestro propio tema html, pueden aprender mas de esto ingresando al sitio oficial.

Resultado

Al final obtendrás un directorio apidoc y dentro veras varios archivos web.
Si abres el index.html en tu navegador podrás ver la web completa con todos los métodos que hayas documentado.

Listo! ya tenemos nuestra documentación en un agradable formato html que se puede leer y entender, accesible desde el navegador, ahora lo que tienes que hacer es hospedarla en algun servidor para que se pueda acceder públicamente, puedes hacerlo utilizando github pages.

Comentarios