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

Artículo
03/17/2024

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.

Screenshot of the A S P dot NET A P I help page, showing the available A P I products to select from and their descriptions.

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.

Screenshot of the Web A P I project template's menu options, circling the area and help page folders.

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.

Screenshot of the home page, pointing to the A P I clickable letters that will open the link to the help page.

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

Screenshot of the A P I summary help page, showing the different A P I values and their description.

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 la tabla se generan dinámicamente mediante la interfaz IApiExplorer. (Hablaré con mayor detalle de 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.

Screenshot of one of the A P I selection values, showing the response information and response body formats.

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 NuGety, 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 BasicInstall-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 á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 quite la marca de comentario de 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.

Screenshot of the project's drop-down menu in the solution explorer window, highlighting the build option.

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

Screenshot of the Output dialog box, showing the output path and the option to select the X M L documentation file.

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 símbolo de intercalación en la línea situada encima del método y escribe tres barras diagonales, 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.

Screenshot of the A P I table in the help pages, showing the documentation string in the A P I value and description.

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).

Una mirada al interior

Las páginas de ayuda se basan en la clase ApiExplorer, que forma parte del marco de API web. La claseApiExplorer 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 interfazIDocumentationProvider. Como ha visto anteriormente, la biblioteca 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 la ApiDescription y objetosApiParameterDescription.

Pasos siguientes

No se limita 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:

Compartir vía