3 etapas fáceis para criar documentações WebAPI

Por padrão, a página de Ajuda da API criada por Microsoft.AspNet.WebApi.HelpPagenão contém documentação. Veremos que todas as ApiControllerações estão listadas comNo documentation available.

Para habilitar a documentação, só precisamos seguir três etapas fáceis.

Etapa 1 – no nível do controlador

Para fins de teste, um novo ApiControlleré criado, denominado DocumentationsController.

public class DocumentationsController : ApiController
{
    // GET api/documentation
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }
....

Clique ///antes da ação do controlador para obter a documentação.

// GET api/documentation
/// <summary>
/// This is how we create a documentation
/// </summary>
/// <returns></returns>
public IEnumerable<string> Get()
....

Para obter mais informações sobre o que pode ser documentado, você pode clicar em “<” para abrir o IntelliSense ou ir para a página MSDN .

Etapa 2 – Construir Propriedade

Traga a página Propriedades do projeto e configure a saída xml para documentação. Neste exemplo, o arquivo de documentação seria .App_Data\Documentation.XML

Etapa 3 – Configuração da página de ajuda

Para configurar o HelpPageConfig para usar nosso arquivo xml de documentação, vá para .~\Areas\HelpPage\HelpPageConfig.cs

Por padrão, a declaração é comentada. Use essa declaração e indique a localização do nosso arquivo xml:config.SetDocumentationProviderDocumentationProvider

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/Documentation.xml")));

Agora podemos construir e atualizar a página de documentação da API:

Claro, o arquivo de documentação também é criado:

Cenário

Observe que a documentação é exibida corretamente. Muito fácil, hein ?!