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.
Si ejecutamos la aplicación veremos en el menú superior el acceso API, el cual nos redirigirá al contenido de esa área.
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.
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:
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:
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:
| using System.Diagnostics.CodeAnalysis; | |
| using System.Net.Http.Headers; | |
| using System.Web; | |
| using System.Web.Http; | |
| namespace WebApi.Areas.HelpPage | |
| { | |
| /// <summary> | |
| /// Use this class to customize the Help Page. | |
| /// For example you can set a custom <see cref="System.Web.Http.Description.IDocumentationProvider"/> to supply the documentation | |
| /// or you can provide the samples for the requests/responses. | |
| /// </summary> | |
| public static class HelpPageConfig | |
| { | |
| public static void Register(HttpConfiguration config) | |
| { | |
| // Uncomment the following to use the documentation from XML documentation file. | |
| config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml"))); | |
| } | |
| } | |
| } |
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:
| using System.Collections.Generic; | |
| using System.Web.Http; | |
| namespace WebApi.Controllers | |
| { | |
| public class ValuesController : ApiController | |
| { | |
| /// <summary> | |
| /// Recolecta información de distintos sitios para encontrar todos los valores. | |
| /// </summary> | |
| /// <returns>Todos los valores disponibles en el universo.</returns> | |
| public IEnumerable<string> Get() | |
| { | |
| return new string[] { "value1", "value2" }; | |
| } | |
| } | |
| } |
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:
Y si vamos al detalle en la parte del Response estará nuestro comentario:
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!!
Un comentario sobre “ASP.NET WebApi: Documentación automática de nuestras API’s”