Creación de páginas de ayuda para ASP.NET API web

En este tutorial con código se muestra cómo crear páginas de ayuda para ASP.NET API web en ASP.NET 4.x.

Al crear una API web, a menudo resulta útil crear una página de ayuda para que otros desarrolladores sepan cómo llamar a la API. Puede crear manualmente toda la documentación, pero es mejor generar automáticamente tanto como sea posible. Para facilitar esta tarea, ASP.NET API web proporciona una biblioteca para generar automáticamente páginas de ayuda en tiempo de ejecución.

Captura de pantalla de la página de ayuda de A S P dot NET A P I, en la que se muestran los productos A P I disponibles para seleccionar y sus descripciones.

Creación de páginas de ayuda de API

Instale ASP.NET y Web Tools 2012.2 Update. Esta actualización integra las páginas de ayuda en la plantilla de proyecto de API web.

A continuación, cree un nuevo proyecto de ASP.NET MVC 4 y seleccione la plantilla de proyecto de API web. La plantilla de proyecto crea un controlador de API de ejemplo denominado ValuesController. La plantilla también crea las páginas de ayuda de la API. Todos los archivos de código de la página de ayuda se colocan en la carpeta Áreas del proyecto.

Captura de pantalla de las opciones de menú de la plantilla de proyecto de Web A P I, rodeando el área y las carpetas de la página de ayuda.

Al ejecutar la aplicación, la página principal contiene un vínculo a la página de ayuda de la API. En la página principal, la ruta de acceso relativa es /Help.

Captura de pantalla de la página principal, señalando las letras A P I clicables que abrirán el enlace a la página de ayuda.

Este vínculo le lleva a una página de resumen de API.

Captura de pantalla de la página de ayuda de resumen de A P I, en la que se muestran los distintos valores de A P I y su descripción.

La vista MVC de esta página se define en Areas/HelpPage/Views/Help/Index.cshtml. Puede editar esta página para modificar el diseño, la introducción, el título, los estilos, etc.

La parte principal de la página es una tabla de API, agrupada por controlador. Las entradas de tabla se generan dinámicamente mediante la interfaz IApiExplorer . (Hablaré más sobre esta interfaz más adelante). Si agrega un nuevo controlador de API, la tabla se actualiza automáticamente en tiempo de ejecución.

La columna "API" enumera el método HTTP y el URI relativo. La columna "Descripción" contiene documentación para cada API. Inicialmente, la documentación es simplemente texto de marcador de posición. En la sección siguiente, le mostraré cómo agregar documentación a partir de comentarios XML.

Cada API tiene un vínculo a una página con información más detallada, incluidos los cuerpos de solicitud y respuesta de ejemplo.

Captura de pantalla de uno de los valores de selección de A P I, en la que se muestran los formatos de información de respuesta y cuerpo de respuesta.

Agregar páginas de ayuda a un proyecto existente

Puede agregar páginas de ayuda a un proyecto de API web existente mediante el Administrador de paquetes NuGet. Esta opción es útil para empezar desde una plantilla de proyecto diferente a la plantilla de "API web".

En el menú Herramientas , seleccione Administrador de paquetes NuGet y, a continuación, seleccione Consola del Administrador de paquetes. En la ventana Consola del Administrador de paquetes, escriba uno de los siguientes comandos:

Para una aplicación de C# : Install-Package Microsoft.AspNet.WebApi.HelpPage

Para una aplicación de Visual Basic : Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

Hay dos paquetes, uno para C# y otro para Visual Basic. Asegúrese de usar el que coincida con el proyecto.

Este comando instala los ensamblados necesarios y agrega las vistas MVC para las páginas de ayuda (ubicadas en la carpeta Areas/HelpPage). Deberá agregar manualmente un vínculo a la página ayuda. El URI es /Help. Para crear un vínculo en una vista de razor, agregue lo siguiente:

@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)

Además, asegúrese de registrar las áreas. En el archivo Global.asax, agregue el código siguiente al método Application_Start , si aún no lo está:

protected void Application_Start()
{
    // Add this code, if not present.
    AreaRegistration.RegisterAllAreas();

    // ...
}

Adición de documentación de API

De forma predeterminada, las páginas de ayuda tienen cadenas de marcador de posición para la documentación. Puede usar comentarios de documentación XML para crear la documentación. Para habilitar esta característica, abra el archivo Areas/HelpPage/App_Start/HelpPageConfig.cs y descomente la siguiente línea:

config.SetDocumentationProvider(new XmlDocumentationProvider(
    HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

Ahora habilite la documentación XML. En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y seleccione Propiedades. Seleccione la página Compilar .

Captura de pantalla del menú desplegable del proyecto en la ventana del Explorador de soluciones, resaltando la opción de compilación.

En Salida, compruebe el archivo de documentación XML. En el cuadro de edición, escriba "App_Data/XmlDocument.xml".

Captura de pantalla del cuadro de diálogo Salida, en el que se muestra la ruta de salida y la opción para seleccionar el archivo de documentación XML.

A continuación, abra el código del ValuesController controlador de API, que se define en /Controllers/ValuesController.cs. Agregue algunos comentarios de documentación a los métodos del controlador. Por ejemplo:

/// <summary>
/// Gets some very important data from the server.
/// </summary>
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

/// <summary>
/// Looks up some data by ID.
/// </summary>
/// <param name="id">The ID of the data.</param>
public string Get(int id)
{
    return "value";
}

Nota:

Sugerencia: Si coloca el cursor sobre la línea del método y escribe tres barras inclinadas, Visual Studio inserta automáticamente los elementos XML. A continuación, puede rellenar los espacios en blanco.

Ahora compile y vuelva a ejecutar la aplicación y vaya a las páginas de ayuda. Las cadenas de documentación deben aparecer en la tabla de API.

Captura de pantalla de la tabla A P I en las páginas de ayuda, en la que se muestra la cadena de documentación en el valor y la descripción de A P I.

La página de ayuda lee las cadenas del archivo XML en tiempo de ejecución. (Al implementar la aplicación, asegúrese de implementar el archivo XML).

Bajo la capucha

Las páginas de ayuda se basan en la clase ApiExplorer , que forma parte del marco de api web. La clase ApiExplorer proporciona la materia prima para crear una página de ayuda. Para cada API, ApiExplorer contiene una apiDescription que describe la API. Para ello, se define una "API" como la combinación del método HTTP y el URI relativo. Por ejemplo, estas son algunas API distintas:

  • GET /api/Products
  • GET /api/Products/{id}
  • POST /api/Products

Si una acción de controlador admite varios métodos HTTP, ApiExplorer trata cada método como una API distinta.

Para ocultar una API de ApiExplorer, agregue el atributo ApiExplorerSettings a la acción y establezca IgnoreApi en true.

[ApiExplorerSettings(IgnoreApi=true)]
public HttpResponseMessage Get(int id) {  }

También puede agregar este atributo al controlador para excluir todo el controlador.

La clase ApiExplorer obtiene cadenas de documentación de la interfaz IDocumentationProvider . Como has visto anteriormente, la biblioteca de páginas de ayuda proporciona un IDocumentationProvider que obtiene documentación de cadenas de documentación XML. El código se encuentra en /Areas/HelpPage/XmlDocumentationProvider.cs. Puede obtener documentación de otro origen escribiendo su propio IDocumentationProvider. Para conectarlo, llame al método de extensión SetDocumentationProvider, definido en HelpPageConfigurationExtensions.

ApiExplorer llama automáticamente a la interfaz IDocumentationProvider para obtener cadenas de documentación para cada API. Los almacena en la propiedad Documentation de los objetos ApiDescription y ApiParameterDescription .

Pasos siguientes

No estás limitado a las páginas de ayuda que se muestran aquí. De hecho, ApiExplorer no se limita a crear páginas de ayuda. Yao Huang Lin ha escrito algunas entradas de blog excelentes para que pienses fuera de la caja:

  • Last updated on