Criando páginas de ajuda para ASP.NET Web API

Artigo
06/16/2023

Este tutorial com código mostra como criar páginas de ajuda para ASP.NET Web API no ASP.NET 4.x.

Quando você cria uma API Web, geralmente é útil criar uma página de ajuda para que outros desenvolvedores saibam como chamar sua API. Você pode criar toda a documentação manualmente, mas é melhor gerar automaticamente o máximo possível. Para facilitar essa tarefa, ASP.NET Web API fornece uma biblioteca para gerar automaticamente páginas de ajuda em tempo de execução.

Captura de tela da página de ajuda do API do API do AZ do AZ, mostrando os produtos AP I disponíveis para seleção e suas descrições.

Criando páginas de ajuda da API

Instale ASP.NET and Web Tools atualização 2012.2. Essa atualização integra páginas de ajuda ao modelo de projeto da API Web.

Em seguida, crie um novo projeto ASP.NET MVC 4 e selecione o modelo de projeto da API Web. O modelo de projeto cria um controlador de API de exemplo chamado ValuesController. O modelo também cria as páginas de ajuda da API. Todos os arquivos de código da página de ajuda são colocados na pasta Áreas do projeto.

Captura de tela das opções de menu do modelo de projeto web AP I, circulando as pastas da área e da página de ajuda.

Quando você executa o aplicativo, a home page contém um link para a página de ajuda da API. Na home page, o caminho relativo é /Help.

Captura de tela da home page apontando para as letras clicáveis do API que abrirão o link para a página de ajuda.

Esse link leva você a uma página de resumo da API.

Captura de tela da página de ajuda de resumo de API, mostrando os diferentes valores de API e sua descrição.

A exibição MVC desta página é definida em Areas/HelpPage/Views/Help/Index.cshtml. Você pode editar esta página para modificar o layout, a introdução, o título, os estilos e assim por diante.

A parte main da página é uma tabela de APIs, agrupadas por controlador. As entradas de tabela são geradas dinamicamente, usando a interface IApiExplorer . (Falarei mais sobre essa interface posteriormente.) Se você adicionar um novo controlador de API, a tabela será atualizada automaticamente em tempo de execução.

A coluna "API" lista o método HTTP e o URI relativo. A coluna "Descrição" contém a documentação de cada API. Inicialmente, a documentação é apenas texto de espaço reservado. Na próxima seção, mostrarei como adicionar documentação de comentários XML.

Cada API tem um link para uma página com informações mais detalhadas, incluindo corpos de solicitação e resposta de exemplo.

Captura de tela de um dos valores de seleção de API, mostrando as informações de resposta e os formatos do corpo da resposta.

Adicionando páginas de ajuda a um projeto existente

Você pode adicionar páginas de ajuda a um projeto de API Web existente usando o Gerenciador de Pacotes NuGet. Essa opção é útil para começar com um modelo de projeto diferente do modelo de "API Web".

No menu Ferramentas , selecione Gerenciador de Pacotes NuGet e, em seguida, selecione Console do Gerenciador de Pacotes. Na janela Console do Gerenciador de Pacotes , digite um dos seguintes comandos:

Para um aplicativo C# : Install-Package Microsoft.AspNet.WebApi.HelpPage

Para um aplicativo do Visual Basic : Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

Há dois pacotes, um para C# e outro para o Visual Basic. Certifique-se de usar aquele que corresponde ao seu projeto.

Esse comando instala os assemblies necessários e adiciona os modos de exibição MVC para as páginas de ajuda (localizadas na pasta Areas/HelpPage). Você precisará adicionar manualmente um link à página ajuda. O URI é /Help. Para criar um link em uma exibição razor, adicione o seguinte:

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

Além disso, registre áreas. No arquivo Global.asax, adicione o seguinte código ao método Application_Start , se ele ainda não estiver lá:

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

    // ...
}

Adicionando documentação da API

Por padrão, as páginas de ajuda têm cadeias de caracteres de espaço reservado para documentação. Você pode usar comentários de documentação XML para criar a documentação. Para habilitar esse recurso, abra o arquivo Areas/HelpPage/App_Start/HelpPageConfig.cs e remova a marca de comentário da seguinte linha:

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

Agora, habilite a documentação XML. Em Gerenciador de Soluções, clique com o botão direito do mouse no projeto e selecione Propriedades. Selecione a página Compilar .

Captura de tela do menu suspenso do projeto na janela do gerenciador de soluções, realçando a opção de build.

Em Saída, marcar arquivo de documentação XML. Na caixa de edição, digite "App_Data/XmlDocument.xml".

Captura de tela da caixa de diálogo Saída mostrando o caminho de saída e a opção para selecionar o arquivo de documentação X M L.

Em seguida, abra o código para o ValuesController controlador de API, que é definido em /Controllers/ValuesController.cs. Adicione alguns comentários de documentação aos métodos do controlador. Por exemplo:

/// <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";
}

Observação

Dica: se você posicionar o cursor na linha acima do método e digitar três barras de avanço, o Visual Studio inserirá automaticamente os elementos XML. Em seguida, você pode preencher os espaços em branco.

Agora, compile e execute o aplicativo novamente e navegue até as páginas de ajuda. As cadeias de caracteres de documentação devem aparecer na tabela de API.

Captura de tela da tabela API nas páginas de ajuda, mostrando a cadeia de caracteres de documentação no valor e na descrição do API.

A página de ajuda lê as cadeias de caracteres do arquivo XML em tempo de execução. (Ao implantar o aplicativo, certifique-se de implantar o arquivo XML.)

Nos Bastidores

As páginas de ajuda são criadas sobre a classe ApiExplorer , que faz parte da estrutura da API Web. A classe ApiExplorer fornece a matéria-prima para criar uma página de ajuda. Para cada API, ApiExplorer contém uma ApiDescription que descreve a API. Para essa finalidade, uma "API" é definida como a combinação do método HTTP e do URI relativo. Por exemplo, aqui estão algumas APIs distintas:

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

Se uma ação do controlador der suporte a vários métodos HTTP, o ApiExplorer tratará cada método como uma API distinta.

Para ocultar uma API do ApiExplorer, adicione o atributo ApiExplorerSettings à ação e defina IgnoreApi como true.

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

Você também pode adicionar esse atributo ao controlador para excluir todo o controlador.

A classe ApiExplorer obtém cadeias de caracteres de documentação da interface IDocumentationProvider . Como você viu anteriormente, a biblioteca páginas de ajuda fornece um IDocumentationProvider que obtém a documentação de cadeias de caracteres de documentação XML. O código está localizado em /Areas/HelpPage/XmlDocumentationProvider.cs. Você pode obter a documentação de outra fonte escrevendo seu próprio IDocumentationProvider. Para conectá-lo, chame o método de extensão SetDocumentationProvider , definido em HelpPageConfigurationExtensions

O ApiExplorer chama automaticamente a interface IDocumentationProvider para obter cadeias de caracteres de documentação para cada API. Ele os armazena na propriedade Documentation dos objetos ApiDescription e ApiParameterDescription .

Próximas etapas

Você não está limitado às páginas de ajuda mostradas aqui. Na verdade, a ApiExplorer não se limita à criação de páginas de ajuda. Yao Huang Lin escreveu algumas ótimas postagens no blog para fazer você pensar fora da caixa:

Partilhar via