В этом сообщении блога мы более подробно рассмотрим ApiExplorer, который является реализацией IApiExplorer по умолчанию, и посмотрим, как он может быстро создавать веб-документацию для доступного REST API. Эта документация будет содержать различную информацию, такую как правильные URL-адреса, допустимые методы HTTP и параметры, ожидаемые для запросов.
Такая информация для вашего REST-сервиса позволит сторонним разработчикам, использующим ваш API, точно знать, как правильно вызывать его части.
Возможно, самое лучшее в такой странице веб-документации — это то, что она автоматически обновляется при обновлении REST API.
APIExplorer
Основная цель этого класса — создание коллекции элементов ApiDescription. Это делается путем статической проверки маршрутов и доступных действий внутри ваших контроллеров.Каждый элемент ApiDescription описывает API, доступный через вашу службу.
Как видно на упрощенной схеме (рис.
1), ApiDescription содержит базовую информацию, такую как HttpMethod, RelativePath, Documentation и т. д. Но кроме того, он содержит элемент APIдескриптор , который является частью ядра WebAPI, которая знает все о соответствующем действии.
Вы можете использовать этот элемент для доступа к обширной информации, такой как имя действия, тип возвращаемого значения, настраиваемые атрибуты и т. д. Аналогичным образом вы можете использовать элемент ПараметрДескриптор изучить ожидаемые параметры этого API. 
Рисунок 1. Диаграмма классов APIDescription
Давайте посмотрим, как мы можем создать страницу помощи.
Создание страницы справки с использованием API
Для простоты я предположу, что мы используем нашу службу REST вместе с ASP.NET MVC. Другие идеи реализации вы можете увидеть ниже в разделе «Другие реализации».
Пример
Например, я использую стандартный шаблон «Веб-API».
Рис.
2. Выбор проекта веб-API По умолчанию этот шаблон содержит HomeController MVC и ValuesController веб-API. Давайте изменим действие Index в HomeController, чтобы отобразить нашу страницу справки.
Шаг 1. Используйте ApiExplorer в представлении
Давайте добавим следующие две строки кода в действие Index:public ActionResult Index() { var apiExplorer = GlobalConfiguration.Configuration.Services.GetApiExplorer(); return View(apiExplorer); }
Шаг 2. Настройте представление для отображения API
В Index.cshtml мы можем указать тип модели как IApiExplorer: @model System.Web.Http.Description.IApiExplorer Затем мы можем перебрать все элементы Model.ApiDescriptions, чтобы отобразить поддерживаемые методы HTTP, относительные URL-адреса, описания действий и ожидаемые параметры.
@foreach (var api in Model.ApiDescriptions)
{
<li>
<h5>@api.HttpMethod @api.RelativePath</h5>
<blockquote>
<p>@api.Documentation</p>
@if (api.ParameterDescriptions.Count > 0)
{
<h6>Parameters</h6>
<ul>
@foreach (var parameter in api.ParameterDescriptions)
{
<li>@parameter.Name: @parameter.Documentation (@parameter.Source)</li>
}
</ul>
}
</blockquote>
</li>
}
Конечно, вы можете настроить свою HTML-разметку так, как захотите.
Ниже приведен полный код представления: @model System.Web.Http.Description.IApiExplorer
<div id="body">
<section class="featured">
<div class="content-wrapper">
<hgroup class="title">
<h1>ASP.NET Web API Help Page</h1>
</hgroup>
</div>
</section>
<section class="content-wrapper main-content clear-fix">
<h3>APIs</h3>
<ul>
@foreach (var api in Model.ApiDescriptions)
{
<li>
<h5>@api.HttpMethod @api.RelativePath</h5>
<blockquote>
<p>@api.Documentation</p>
@if (api.ParameterDescriptions.Count > 0)
{
<h6>Parameters</h6>
<ul>
@foreach (var parameter in api.ParameterDescriptions)
{
<li>@parameter.Name: @parameter.Documentation (@parameter.Source)</li>
}
</ul>
}
</blockquote>
</li>
}
</ul>
</section>
</div>
Теперь, после запуска приложения, вы должны увидеть следующую страницу с описанием доступного REST API (рис.
3).
Рис.
3. Страница веб-документации Если вы присмотритесь, в описании API просто написано «Документация для XYZ», что, естественно, не очень полезно.
Добавим немного полезной информации.
Шаг 3. Добавьте документацию
Во время создания документации для API наш ApiExplorer запрашивает IDocumentationProvider, чтобы предоставить необходимую информацию.IDocumentationProvider — это абстрактный механизм, который позволяет вам определить собственный способ получения информации для документирования действий API. Это позволяет вам реализовать собственный IDocumentationProvider, который будет получать информацию из нужного вам источника.
Ниже вы можете найти пример реализации IDocumentationProvider, который извлекает информацию из комментариев документации C#.
public class XmlCommentDocumentationProvider : IDocumentationProvider
{
XPathNavigator _documentNavigator;
private const string _methodExpression = "/doc/members/member[@name='M:{0}']";
private static Regex nullableTypeNameRegex = new Regex(@"(.
*\.
Nullable)" + Regex.Escape("`1[[") + "([^,]*),.
*"); public XmlCommentDocumentationProvider(string documentPath) { XPathDocument xpath = new XPathDocument(documentPath); _documentNavigator = xpath.CreateNavigator(); } public virtual string GetDocumentation(HttpParameterDescriptor parameterDescriptor) { ReflectedHttpParameterDescriptor reflectedParameterDescriptor = parameterDescriptor as ReflectedHttpParameterDescriptor; if (reflectedParameterDescriptor != null) { XPathNavigator memberNode = GetMemberNode(reflectedParameterDescriptor.ActionDescriptor); if (memberNode != null) { string parameterName = reflectedParameterDescriptor.ParameterInfo.Name; XPathNavigator parameterNode = memberNode.SelectSingleNode(string.Format("param[@name='{0}']", parameterName)); if (parameterNode != null) { return parameterNode.Value.Trim(); } } } return "No Documentation Found."; } public virtual string GetDocumentation(HttpActionDescriptor actionDescriptor) { XPathNavigator memberNode = GetMemberNode(actionDescriptor); if (memberNode != null) { XPathNavigator summaryNode = memberNode.SelectSingleNode("summary"); if (summaryNode != null) { return summaryNode.Value.Trim(); } } return "No Documentation Found."; } private XPathNavigator GetMemberNode(HttpActionDescriptor actionDescriptor) { ReflectedHttpActionDescriptor reflectedActionDescriptor = actionDescriptor as ReflectedHttpActionDescriptor; if (reflectedActionDescriptor != null) { string selectExpression = string.Format(_methodExpression, GetMemberName(reflectedActionDescriptor.MethodInfo)); XPathNavigator node = _documentNavigator.SelectSingleNode(selectExpression); if (node != null) { return node; } } return null; } private static string GetMemberName(MethodInfo method) { string name = string.Format("{0}.
{1}", method.DeclaringType.FullName, method.Name); var parameters = method.GetParameters(); if (parameters.Length != 0) { string[] parameterTypeNames = parameters.Select(param => ProcessTypeName(param.ParameterType.FullName)).
ToArray(); name += string.Format("({0})", string.Join(",", parameterTypeNames)); } return name; } private static string ProcessTypeName(string typeName) { //handle nullable var result = nullableTypeNameRegex.Match(typeName); if (result.Success) { return string.Format("{0}{{{1}}}", result.Groups[1].
Value, result.Groups[2].
Value);
}
return typeName;
}
}
После этого вам необходимо подключить свой собственный IDocumentationProvider. Самый простой способ сделать это — настроить через HttpConfiguration. Обратите внимание, что XmlCommentDocumentationProvider должен знать, где находится файл комментариев XML. var config = GlobalConfiguration.Configuration;
config.Services.Replace(typeof(IDocumentationProvider),
new XmlCommentDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/MyApp.xml")));
Вы можете убедиться, что генерация файла XML-документации включена в настройках проекта (рис.
4).
Рис.
4. Настройка опции создания файла документации
После этого убедитесь, что ваш код содержит комментарии к документации: 
Наконец, снова запустите проект и убедитесь, что документация из вашего кода теперь доступна на странице веб-документации вашего REST API (рис.
5).
Рис.
5. Страница веб-документации с описанием методов
Исключение контроллера/действия из документации
По некоторым причинам вам может потребоваться исключить контроллер или действие из создания документации API. Для этого можно использовать специальный атрибут ApiExplorerSettingsAttribute: public class ValuesController : ApiController
{
[ApiExplorerSettings(IgnoreApi = true)]
public void MySpecialAction()
{
}
}Его также можно использовать для контроллера:
[ApiExplorerSettings(IgnoreApi = true)]
public class MySpecialController : ApiController
{Другие реализации
То, что я показал выше, — это лишь один из способов реализации страницы веб-документации.Но может быть много других способов, вот, например, еще одна идея:
- Создайте собственную реализацию ApiController (например, HelpController).
Внутри контроллера у вас будет действие GET, которое возвращает информацию об API (в любом формате, который вы хотите).
Внутри HelpController будет использовать ApiExplorer и всю доступную через него информацию.
Преимущество этого подхода в том, что он будет работать как в автономном режиме, так и в качестве веб-службы.
Примечание переводчика
В этой статье описываются будущие функции, которые будут добавлены в ASP.NET WebAPI. Вы можете попробовать это сегодня, установив необходимые пакеты из репозитория WebAPI. aspnetwebstack.codeplex.com/./353867
Подробнее о том, как это можно сделать, написано в отдельная статья .Теги: #Разработка сайтов #.
NET #остальные #ASP.NET #документация #asp.net webapi
-
Новая Эра Брендинга
19 Oct, 24 -
Как Загрузить Данные В Google Bigquery
19 Oct, 24 -
Верни Мне Мои Данные, Жесткий Диск!
19 Oct, 24 -
Молодая Женщина
19 Oct, 24
