ASP.NET WebApi: Documentación automática de nuestras API’s

Uno de los puntos importantes en el desarrollo de nuestras API’s RESTfull es tener una documentación adecuada para permitir y facilitar la tarea de integración de distintos clientes. Esto se debe de cierta forma a la diferencia que existe con respecto a un servicio SOAP, donde sí existe un archivo que contiene toda la definición del servicio y se utiliza para su integración.

En el caso de ASP.NET y sus servicios WebApi, esta funcionalidad viene integrada de forma nativa en el proyecto básico de este tipo. Luego de crearlo podremos ver la existencia del área HelpPage, la cual se encarga de crear la estructura de documentación asociada a nuestra API.

WebApiDoc - Area

Si ejecutamos la aplicación veremos en el menú superior el acceso API, el cual nos redirigirá al contenido de esa área.

WebApiDoc - Access

Una vez allí veremos que contamos con un listado de los métodos disponibles en la API Values, la cual está disponible por el controlador ValuesController creado por defecto por el template de proyecto.

WebApiDoc - BasicAPISummary
Listado de métodos de nuestros controladores WebApi

Y cuando accedemos a un método en particular (en este caso Get) tendremos el detalle de la información del Request y Response del mismo:

WebApiDoc - BasicAPIDetail
Detalle del método de nuestra API, generado de forma automática

Lo que cabe destacar es que toda esta información es generada de forma automática por la lógica ubicada en el área HelpPage, lo cual nos permite que a medida que vayamos creando nuestras propias API’s, las mismas queden documentadas de forma actualizada sin necesidad de esfuerzo adicional. Muy interesante, no?

La verdad que es una alternativa muy buena para documentar nuestras API’s, ya que además podemos modificar su lógica para nuestros propósitos particulares. Por ejemplo, supongamos que queremos que los comentarios que escribimos en el summary de nuestros métodos aparezca en dicha documentación. Por defecto esto no sucederá, pero podemos hacer algunas modificaciones para que así sea.

Lo primero será configurar nuestro proyecto para que a la hora de compilar genere un archivo Xml asociado con esta información. Para ello vamos a las propiedades del proyecto y dentro de la pestaña “Build” y su sección “Output” marcamos el tilde “XML documentation file” e ingresamos en el campo que se habilita a la derecha el siguiente valor: App_Data\XmlDocument.xml

El resultado debería ser como se ve en la siguiente imagen:

WebApiDoc - XMLProjectChange

Una vez realizado esto deberemos ir al archivo HelpConfig.cs ubicado en Areas\HelpPage\App_Start y en el método Register agregar el código que está a continuación en la línea 18:

NOTA: Acá para simplificar el snippet de código quité las demás líneas siguientes, pero en el archivo real debe quedar todo como está pero solo agregando esa línea.

Lo último que nos queda es agregar algún comentario al método de nuestra API. Siguiendo con el ejemplo usaremos el Get, quedando de la siguiente forma:

Con estos cambios ya debería estar todo configurado, así que ejecutemos nuestra aplicación. Si vamos al listado de métodos de la API podremos apreciar que en el Get ya contamos con la descripción que agregamos:

WebApiDoc - ModifiedAPISummary
Listado de métodos con documentación actualizada

 

Y si vamos al detalle en la parte del Response estará nuestro comentario:

WebApiDoc - ModifiedAPIDetail
Contenido actualizado en detalle del método

 

Como podemos ver con ASP.NET WebApi es realmente muy sencillo mantener la documentación de nuestras API’s, ya que documentando nuestro código estamos documentando de forma simultánea nuestra API. Además de que todo esto está armado a través de código C# que se ejecuta en un sitio ASP.NET MVC, lo cual nos da la posibilidad de personalizarlo según nuestras necesidades.

Espero que les sea útil, gracias por leer!!

Anuncios

Un comentario en “ASP.NET WebApi: Documentación automática de nuestras API’s

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s