Создание страниц справки для веб-API ASP.NET

В этом руководстве с кодом показано, как создать страницы справки для веб-API ASP.NET в ASP.NET 4.x.

При создании веб-API часто бывает полезно создать страницу справки, чтобы другие разработчики знали, как вызывать его. Вы можете создать всю документацию вручную, но лучше автоматически создать как можно больше. Чтобы упростить эту задачу, веб-API ASP.NET предоставляет библиотеку для автоматического создания страниц справки во время выполнения.

Создание страниц справки API

Установите обновление ASP.NET and Web Tools 2012.2. Это обновление интегрирует страницы справки в шаблон проекта веб-API.

Затем создайте проект ASP.NET MVC 4 и выберите шаблон проекта веб-API. Шаблон проекта создает пример контроллера API с именем ValuesController. Шаблон также создает страницы справки API. Все файлы кода для страницы справки помещаются в папку Areas проекта.

При запуске приложения домашняя страница содержит ссылку на страницу справки ПО API. На домашней странице относительный путь — /Help.

По этой ссылке вы перейдете на страницу сводки ПО API.

Представление MVC для этой страницы определено в файле Areas/HelpPage/Views/Help/Index.cshtml. Вы можете изменить эту страницу, чтобы изменить макет, введение, заголовок, стили и т. д.

Main часть страницы представляет собой таблицу API, сгруппированных по контроллеру. Записи таблицы создаются динамически с помощью интерфейса IApiExplorer . (Я подробнее об этом интерфейсе поговорим позже.) При добавлении нового контроллера API таблица автоматически обновляется во время выполнения.

В столбце API перечислены метод HTTP и относительный URI. Столбец "Описание" содержит документацию по каждому API. Изначально документация представляет собой просто замещающий текст. В следующем разделе я покажем, как добавить документацию из комментариев XML.

Каждый API содержит ссылку на страницу с более подробными сведениями, включая примеры текста запроса и ответа.

Добавление страниц справки в существующий проект

Страницы справки можно добавить в существующий проект веб-API с помощью диспетчера пакетов NuGet. Этот параметр полезен при запуске с шаблона проекта, отличного от шаблона "Веб-API".

В меню Сервис выберите Диспетчер пакетов NuGet, а затем консоль диспетчера пакетов. В окне консоль диспетчера пакетов введите одну из следующих команд:

Для приложения C# : Install-Package Microsoft.AspNet.WebApi.HelpPage

Для приложения Visual Basic : Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

Существует два пакета: один для C# и один для Visual Basic. Обязательно используйте тот, который соответствует вашему проекту.

Эта команда устанавливает необходимые сборки и добавляет представления MVC для страниц справки (находятся в папке Areas/HelpPage). Вам потребуется вручную добавить ссылку на страницу справки. Универсальный код ресурса (URI) — /Help. Чтобы создать ссылку в представлении razor, добавьте следующее:

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

Кроме того, обязательно зарегистрируйте области. В файле Global.asax добавьте следующий код в метод Application_Start , если его еще нет:

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

    // ...
}

Документация по добавлению API

По умолчанию страницы справки содержат строки заполнителей для документации. Для создания документации можно использовать комментарии XML-документации . Чтобы включить эту функцию, откройте файл Areas/HelpPage/App_Start/HelpPageConfig.cs и раскомментируйте следующую строку:

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

Теперь включите xml-документацию. В Обозреватель решений щелкните проект правой кнопкой мыши и выберите Свойства. Выберите страницу Сборка .

В разделе Выходные данные проверка XML-файл документации. В поле ввода введите "App_Data/XmlDocument.xml".

Затем откройте код для контроллера ValuesController API, который определен в файле /Controllers/ValuesController.cs. Добавьте некоторые комментарии к документации в методы контроллера. Пример:

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

Примечание

Совет. Если поместить курсор на строку над методом и ввести три косые черты, Visual Studio автоматически вставляет XML-элементы. Затем можно заполнить пробелы.

Теперь выполните сборку и снова запустите приложение и перейдите на страницы справки. Строки документации должны отображаться в таблице API.

Страница справки считывает строки из XML-файла во время выполнения. (При развертывании приложения обязательно разверните XML-файл.)

Под капотом

Страницы справки создаются поверх класса ApiExplorer , который является частью платформы веб-API. Класс ApiExplorer предоставляет исходный материал для создания страницы справки. Для каждого API ApiExplorer содержит описание APIDescription , описывающее API. Для этой цели "API" определяется как сочетание метода HTTP и относительного URI. Например, ниже приведены некоторые отдельные API:

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

Если действие контроллера поддерживает несколько методов HTTP, ApiExplorer рассматривает каждый метод как отдельный API.

Чтобы скрыть API из ApiExplorer, добавьте атрибут ApiExplorerSettings в действие и присвойте IgnoreApi значение true.

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

Этот атрибут также можно добавить в контроллер, чтобы исключить весь контроллер.

Класс ApiExplorer получает строки документации из интерфейса IDocumentationProvider . Как вы видели ранее, библиотека страниц справки предоставляет IDocumentationProvider , который получает документацию из строк XML-документации. Код находится в файле /Areas/HelpPage/XmlDocumentationProvider.cs. Вы можете получить документацию из другого источника, написав собственный IDocumentationProvider. Чтобы подключить его, вызовите метод расширения SetDocumentationProvider , определенный в HelpPageConfigurationExtensions

ApiExplorer автоматически вызывает интерфейс IDocumentationProvider , чтобы получить строки документации для каждого API. Они хранятся в свойстве Documentation объектов ApiDescription и ApiParameterDescription .

Next Steps

Вы не ограничены страницами справки, представленными здесь. На самом деле ApiExplorer не ограничивается созданием страниц справки. Яо Хуан Лин написал несколько больших записей блога, чтобы вы думали из коробки:

• Добавление простого тестового клиента на страницу справки веб-API ASP.NET
• Работа страницы справки веб-API ASP.NET в локальных службах
• Создание страницы справки (или клиента) во время разработки для веб-API ASP.NET
• Настройка страницы расширенной справки