Saltar al contenido

Artículos, tutoriales, trucos, curiosidades, reflexiones y links sobre programación web ASP.NET Core, MVC, Blazor, SignalR, Entity Framework, C#, Azure, Javascript... y lo que venga ;)

17 años online

el blog de José M. Aguilar

Inicio El autor Contactar

Artículos, tutoriales, trucos, curiosidades, reflexiones y links sobre programación web
ASP.NET Core, MVC, Blazor, SignalR, Entity Framework, C#, Azure, Javascript...

¡Microsoft MVP!
martes, 11 de diciembre de 2012
ASP.NETCuando trabajábamos con los Servicios Web de toda la vida, las herramientas de desarrollo incluían sistemas para generar la documentación básica de los servicios que implementábamos. El estándar WSDL (Web Services Description Language), era un lenguaje basado en XML que permitía describir las funcionalidades de un servicio web aportando gran cantidad de detalles sobre las operaciones, tipos de datos, o direcciones de acceso a las mismas.

Gracias a esto, los desarrolladores podíamos conectarnos fácilmente a un servicio para consultar sus especificaciones técnicas, o incluso generar de forma automática código cliente o proxies que facilitaran el acceso remoto a las funciones publicadas en la red.

Y para los que venimos de esos tiempos, una de las primeras dudas que surgen al comenzar a trabajar con WebAPI es si existe algo similar. Y la respuesta es sí, pero no ;-P

De momento no existe ningún estándar ni especificación que permita describir los servicios WebAPI con la riqueza y formalización que permite WSDL. Esta tecnología se basa únicamente en HTTP, por lo que, a lo sumo, podríamos intuir el comportamiento de los sistemas partiendo de las direcciones de los recursos y los verbos HTTP utilizados, siempre que estén diseñados conformes al estilo REST, por supuesto.

Lo que sí tenemos es un paquete, descargable a través de Nuget, que nos puede ayudar bastante a generar páginas de ayuda y documentación para nuestros API partiendo de la documentación XML que incluyamos en el código. A diferencia de WSDL, en este caso no tendremos una definición formal de las operaciones que pueda ser consumida por otros sistemas debido a la ausencia de un estándar para ello, pero sí podremos conseguir un documento bastante razonable para que un desarrollador ser haga una idea clara de cómo usar nuestros servicios.

1. Empezando por el final…

Para que os hagáis una idea del resultado antes de ver cómo conseguirlo, ahí van un par de capturas de pantalla de la página de ayuda generada para un controlador WebAPI como el siguiente:
public class CustomerController: ApiController
{
    /// <summary>
    /// Gets a Customer
    /// </summary>
    /// <param name="id">Customer's Id</param>
    /// <returns>The Customer</returns>
    public Customer Get(int id)
    {
        // Code
    }
    /// <summary>
    /// Creates a new Customer
    /// </summary>
    /// <param name="customer">The customer</param>
    /// <returns>HTTP response with the result of this operation</returns>
    public HttpResponseMessage Post(Customer customer)
    {
        // Code
    }
    /// <summary>
    /// Updates a Customer
    /// </summary>
    /// <param name="customer">The customer</param>
    /// <returns>HTTP response with the result of this operation</returns>
    public HttpResponseMessage Put(int id, Customer customer)
    {
        // Code
    }
    /// <summary>
    /// Deletes a customer
    /// </summary>
    /// <param name="id">Customer's id</param>
    /// <returns>HTTP response with the result of this operation</returns>
    public HttpResponseMessage Delete(int id)
    {
        // Code
    }
}
Las páginas de ayuda generada tienen esta pinta:

Página de ayuda de WebAPI


Página de ayuda de WebAPI
Veamos ahora cómo conseguirlo.

2. Instalación del paquete

El componente que incluye la magia necesaria para generar la documentación se distribuye a través de Nuget, en el paquete Microsoft.AspNet.WebApi.Help. Su instalación, como siempre, es inmediata:
Install-Package Microsoft.AspNet.WebApi.HelpPage –Pre
La única particularidad que podéis ver en la línea anterior es la inclusión del parámetro “–pre”. Esto es necesario en la actualidad porque se trata de un componente en versión preliminar, pero una vez se publique la versión final ya no será necesario. Por tanto, si lo hacéis desde el IDE de Nuget, tenéis que recordar seleccionar la opción de permitir prereleases para que os aparezca el paquete y podáis descargarlo.

imageEn cualquier caso, tras descargar e instalar este paquete, el principal cambio que notaremos en el proyecto es la inclusión de un Área (MVC) llamada HelpPage, tal y como se muestra en la captura de pantalla adjunta.

El código incluido en este área es el responsable de registrar la ruta de acceso a las páginas de ayuda (por defecto en /help), y de procesar las peticiones de consulta. Internamente se usa ApiExplorer, una característica incluida en la última versión de System.Net.Http, que implementa todos los mecanismos de introspección necesarios para obtener las descripciones de las clases y métodos que componen nuestro API.

Dentro de la misma podemos encontrar también el código de la clase XmlDocumentationProvider, que será la encargada de extraer la documentación partiendo de los archivos XML generados durante la compilación a partir de los comentarios incluidos en el código.

3. Activación de comentarios XML

Por tanto, lo siguiente que debemos hacer es activar la generación del archivo XML de documentación en las propiedades del proyecto, indicando su nombre y ubicación:

Activar la documentación XML

Hecho esto, como podremos comprobar la primera vez que compilemos, los comentarios sobre las clases y métodos del proyecto sean incluidos en el archivo XML. Sin embargo, también veremos que tiene un pequeño efecto colateral bastante molesto: Visual Studio mostrará un warning por cada miembro o tipo público que no describamos.

Warning: falta comentario XML

Para solucionarlo, de nuevo sobre la pestaña “Build” de las propiedades del proyecto, podemos desactivar el aviso de warning 1591, que es el que nos está mostrando:

image

4. Registrar y configurar el proveedor de documentación basado en comentarios XML

El siguiente paso es registrar el proveedor XmlDocumentationProvider e informarlo de la ruta donde se encuentra el archivo de documentación generado. Esto lo hacemos descomentando una línea en el archivo /Areas/HelpPage/App_Start/HelpPageConfig.cs y estableciendo la ruta configurada anteriormente:
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("~/bin/WebApiDemo.xml"))
        );

        [...] // Code ommited for brevity
    }
}
¡Y esto es todo lo que hay que hacer! :-) A partir de este momento, ya podremos acceder a la URL /help (o la indicada en la ruta del área) y consultar las ayudas generadas. Por defecto el sistema incluirá documentación para todos los controladores WebAPI del proyecto, salvo aquellos que sean decorados con el atributo ApiExplorerSettings de la siguiente forma:
// This controller will be ignored
[ApiExplorerSettings(IgnoreApi = true)] 
public class MyController : ApiController
{
   [...]
}

5. Personalizar la apariencia y comportamiento

El hecho de que este paquete se distribuya en forma de área tiene como ventaja que su código fuente se introducirá en nuestro proyecto, permitiéndonos modificar con bastante libertad la forma en que estas páginas son generadas.

En el mismo archivo /Areas/HelpPage/App_Start/HelpPageConfig.cs que ya hemos modificado anteriormente es posible modificar diversos aspectos de la documentación, como los valores a usar para los distintos tipos de dato cuando se muestran ejemplos o en acciones concretas, entre otros. Vale la pena echarle un vistazo y jugar con las distintas opciones, que vienen comentadas sobre el código fuente del archivo.

También en la carpeta de vistas del área, ubicada en /Areas/HelpPage/Views encontraremos los archivos .cshtml utilizados para visualizar el índice general y la página de detalle de una acción (index.cshtml y api.cshtml respectivamente), así como las vistas parciales usadas para mostrar cada uno de los elementos mostrados al usuario (controladores o grupos de API, parámetros de las acciones, etc.). También encontraremos un Layout básico en la carpeta /Views/Shared, que por supuesto podemos ignorar completamente si cambiamos la referencia al mismo en el archivo _ViewStart.cshtml que encontramos sobre la misma carpeta de vistas del área. En este artículo podéis encontrar información sobre el contenido de cada archivo y ejemplos de personalizaciones.

Por último, es posible modificar la forma en que se genera el código de ejemplo, que encontraremos implementados en la carpeta /SampleGeneration del área, lo que puede resultar muy útil cuando existe algún motivo que impide que el sistema infiera correctamente los tipos de datos usados para serializarlos (por ejemplo, esto ocurre cuando nuestras acciones retornan un objeto HttpResponseMessage). Podéis ver algunos ejemplos de uso de generadores personalizados en este post.
 
Publicado en Variable not found.

2 Comentarios:

www.laguiadelturista.cl dijo...

quisiera saber como puedo ordenar los endpoint en la documentacion, ya que quisiera ordenar los controladores en forma alfabetica.

José María Aguilar dijo...

Hola,

desconozco si es posible hacerlo para WebAPI (.NET Framework); tampoco tengo forma de probarlo, porque hablamos ya de un marco de trabajo antiguo (el post tiene cerca de 10 años!).

Para ASP.NET Core sí es posible hacerlo, aquí puedes ver un ejemplo: https://stackoverflow.com/a/65771748

Saludos!