WebAPI: автогенерация веб-документации REST APIИсточник: msdnmicrosoft Владимир Юнев
В этой записи блога мы близко рассмотрим ApiExplorer, являющийся реализацией IApiExplorer по умолчанию и увидим как с помощью него можно быстро сгенерировать веб-документацию по доступному REST API. В этой документации будет содержаться разнообразная информация, например, правильные URL, допустимые HTTP-методы, ожидаемые для запросов параметры. Такого рода информация для вашего REST-сервиса позволит сторонним разработчикам, потребляющим ваш API, точно знать как правильно вызывать его части. Наверное, самое приятное в такой странице веб-документации состоит в том, что она будет обновляться автоматически вместе с обновлением вашего REST API. ApiExplorerОсновной целью этого класса является генерирование коллекции элементов ApiDescription. Это производится с помощью статической проверки маршрутов и доступных действий внутри ваших контроллеров. Каждый элемент ApiDescription описывает API доступный через ваш сервис. Как вы можете видеть на упрощенной диаграмме (рисунок 1) ApiDescription содержит базовую информацию такую как, HttpMethod, RelativePath, Documentation и т.д. Но кроме того, он содержит элемент ApiDescriptor, который является частью ядра WebAPI знающей все о соответствующем действии. Вы можете использовать этот элемент для получения доступа к обширной информации, такой как имя действия, возвращаемый тип, пользовательские атрибуты и т.д. Точно так же вы можете использовать элемент ParameterDescriptor для изучения ожидаемых параметров данного API. Рис.1. Диаграмма класса ApiDescription Давайте посмотрим, как мы можем сгенерировать страницу помощи. Генерация страницы помощи по APIДля простоты я буду считать, что мы используем наш REST-сервис вместе с ASP.NET MVC. Другие идеи по реализации вы можете посмотреть ниже в разделе "Другие реализации". ПримерДля примера я использую стандартный шаблон "Web API". Рис.2. Выбор проекта Web API По умолчанию это шаблон содержит MVC-контроллер HomeController и Web API ValuesController. Давайте поменяем действие Index в HomeController для того, чтобы отобразить нашу страницу помощи. Шаг 1. Используем ApiExplorer в представленииДобавим следующие две строки кода в действие Index:
Шаг 2. Настроим представление для отображения APIВ Index.cshtml мы можем указать типом модели IApiExplorer: @model System.Web.Http.Description.IApiExplorer Затем мы можем пройтись по всем элементам Model.ApiDescriptions для отображения поддерживаемых HTTP-методов, относительных URL, описания действий и ожидаемых параметров.
Конечно вы можете настроить свою HTML-разметку так как вам захочется. Ниже полный код для представления:
Теперь, после запуска приложения вы должны увидеть следующую страницу с описанием доступного REST API (рисунок 3). Рис.3. Страница с веб-документацией Если вы взгляните внимательнее, описание API просто говорит "Documentation for XYZ", что естественно не очень полезно. Давайте добавим немного полезной информации. Шаг 3. Добавление документацииВо время генерации документации для API наш ApiExplorer запрашивает IDocumentationProvider для предоставления необходимой информации. IDocumentationProvider - это абстрактный механизм, который позволяет вам определять собственный способ получения информации для документирования действий API. Это позволяет вам реализовать собственный IDocumentationProvider, который будет извлекать информацию из нужного вам источника. Ниже вы можете найти пример реализации IDocumentationProvider, которая извлекает информацию из документирующих комментариев C#.
После этого вам необходимо подключить ваш собственный IDocumentationProvider. Простейшим способом это сделать является конфигурирование через HttpConfiguration. Обратите внимание, что XmlCommentDocumentationProvider должен знать где находится файл XML с комментариями.
Вы можете убедиться в том, что генерация вашего файла XML документации включена в настройках проекта (рисунок 4). Рис.4. Установка параметра генерации файла документации После этого убедитесь, что ваш код содержит комментарии документирования: В заключении, запустите ваш проект снова и убедитесь, что документация из вашего кода теперь доступна на странице веб-документации вашего REST API (рисунок 5). Рис.5. Страница веб-документации с описанием методов Исключение контроллера/действия из документацииПо некоторым причинам может понадобиться исключить контроллер или действие из генерации документации API. Для этого вы можете воспользоваться специальным атрибутом ApiExplorerSettingsAttribute:
Он может применяться и для контроллера:
Другие реализацииТо что я показал выше - это всего лишь один путь для реализации страницы веб-документации. Но могут быть и многие другие пути, вот, для примера, другая идея:
Замечание переводчикаВ статье описан будущий функционал, который будет добавлен в ASP.NET WebAPI. Вы можете попробовать его уже сегодня, установив необходимые пакеты из репозитория WebAPI aspnetwebstack.codeplex.com/.../353867 подробнее о том, как это можно сделать написано в отдельной статье. Автор статьи: Владимир Юнев. |