为 ASP.NET Web API 创建帮助页面(转载)

转载地址:http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages

当创建web API 时,经常要创建一个帮助页,以便其他开发人员知道如何调用您的 API。您可以手动创建的所有文档,但最好是尽可能多地自动生成。

为了简化这一任务,ASP.NET Web API 提供一个库自动生成帮助页。

创建 API 帮助页

安装ASP.NET 和 Web 工具 2012.2 的更新。此更新集成到 Web API 项目模板的帮助页面。

接下来,创建一个新的 ASP.NET MVC 4 项目并选择 Web API 项目模板。项目模板创建名为ValuesController的示例 API 控制器。该模板还会创建 API 的帮助页面。所有的帮助页的代码文件都放在项目的区域文件夹。

当您运行该应用程序时,主页页面包含 API 的帮助页面的链接。从主页上,相对路径是 /Help。

此链接为您带到 API 的摘要页。

此页的 MVC 视图是在 Areas/HelpPage/Views/Help/Index.cshtml 中定义的。您可以编辑此页后,可以修改布局、 介绍、 标题、 样式和等等。

该页面的主要部分是一个table布局的控制器的Api。使用IApiExplorer接口条目是动态生成的。(我会稍后再谈谈此接口)。如果您添加一个新的 API 控制器,在运行时自动更新的界面。

"API"列列出了 HTTP 方法和相对 URI。"说明"列中包含每个 API 的文档。最初,该文档是只是占位符文本。在接下来的部分中,我将展示如何从 XML 注释添加文档。

每个 API 已链接到一个网页提供更详细信息,包括示例请求和响应的代码。

将帮助页面添加到现有的项目

通过使用 NuGet 程序包管理器,可以将帮助页面添加现有 Web API 项目。

工具菜单中,选择库程序包管理器,然后选择程序包管理器控制台。在程序包管理器控制台窗口中,键入下列命令之一:

C#应用程序:Install-Package Microsoft.AspNet.WebApi.HelpPage

此命令安装必要的程序集并添加 MVC 视图 (位于Area/HelpPage 文件夹)的帮助页。您需要手动添加到帮助页的链接。URI 是 /Help。要在 razor 视图中创建链接,请添加以下内容:

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

此外,还要确保要注册的Area。在 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/ValuesControler.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类,这是 Web API 框架的一部分。ApiExplorer类提供了用于创建一个帮助页提供程序。对于每个 API, ApiExplorer包含描述一些 API 的ApiDescription 。为此目的,"API"定义为组合的 HTTP 方法和相对 URI。例如,下面是一些不同的 Api:

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

如果一个控制器动作支持多个 HTTP 方法, ApiExplorer会将每个方法视为不同的 API。

若要隐藏从ApiExplorer的 API,将ApiExplorerSettings属性添加到操作,将IgnoreApi设置为 true。

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

也可以将此属性添加到控制器,来排除整个控制器。

ApiExplorer 类从IDocumentationProvider接口获取文档字符串。正如您看到的早些时候,帮助页面库提供了从 XML 文档字符串中获取文件的IDocumentationProvider 。该代码位于 /Areas/HelpPage/XmlDocumentationProvider.cs。通过编写您自己的IDocumentationProvider,可以从另一个源获取文档。若要它捆绑起来,请在HelpPageConfigurationExtensions中定义的SetDocumentationProvider扩展方法

ApiExplorer自动调用IDocumentationProvider接口来获取每个 API 的文档字符串。它将它们存储在文档属性中的ApiDescriptionApiParameterDescription的对象。

时间: 2024-11-05 11:45:00

为 ASP.NET Web API 创建帮助页面(转载)的相关文章

asp.net web api 测试帮助页面建立并测试

现在使用WEB API来开发,越来越流行. 在开发过程中的测试调试,可以使用Fiddler等工具来帮助测试外,还有: 在asp.net 中有种方式可以建立一个帮助测试页面来帮助测试调试API接口,非常的方便. 英文原文地址: http://blogs.msdn.com/b/yaohuang1/archive/2012/12/02/adding-a-simple-test-client-to-asp-net-web-api-help-page.aspx 网上朋友的中文博客: 就会很清楚地知道如何调

为 ASP.NET Web API 创建帮助页

http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages 以前实例中一直有这个xmldocument但是一直没有用过,今天特别查找了下资料,原来是这样子用的.记录一下.

ASP.NET Web API 创建帮助页

1. 安装 Microsoft.AspNet.WebApi.HelpPage 程序包 Install-Package Microsoft.AspNet.WebApi.HelpPage 2. 注册 Area protected void Application_Start() { AreaRegistration.RegisterAllAreas(); } 3. HelpPageConfig 启用 SetDocumentationProvider WebApplication/Areas/Help

【ASP.NET Web API教程】2.4 创建Web API的帮助页面

参考页面: http://www.yuanjiaocheng.net/CSharp/csharprumenshili.html http://www.yuanjiaocheng.net/entity/mode-first.html http://www.yuanjiaocheng.net/entity/database-first.html http://www.yuanjiaocheng.net/entity/choose-development-approach.html http://ww

【ASP.NET Web API教程】2.4 创建Web API的帮助页面[转]

注:本文是[ASP.NET Web API系列教程]的一部分,如果您是第一次看本博客文章,请先看前面的内容. 2.4 Creating a Help Page for a Web API2.4 创建Web API帮助页面 本文引自:http://www.asp.net/web-api/overview/creating-web-apis/creating-a-help-page-for-a-web-api By Mike Wasson | August 3, 2012作者:Mike Wasson

ASP.NET Web API中的依赖注入

小分享:我有几张阿里云优惠券,用券购买或者升级阿里云相应产品最多可以优惠五折!领券地址:https://promotion.aliyun.com/ntms/act/ambassador/sharetouser.html?userCode=ohmepe03 什么是依赖注入 依赖,就是一个对象需要的另一个对象,比如说,这是我们通常定义的一个用来处理数据访问的存储,让我们用一个例子来解释,首先,定义一个领域模型如下: namespace Pattern.DI.MVC.Models{ public cl

JQuery + ASP.Net Web API一个简单应用

一.使用JQuery + ASP.Net Web API创建一个简单的CRUD应用 该Demo模拟联系人管理(Contact).页面加载时列出所有的联系人,同时支持增.删.改操作.页面效果如下: 二.通过ASP.NET Web API提供服务 通过Visual Studio创建一个Web API项目,在Model中增加表示联系人的Contact,定义如下: public class Contact { public string Id { get; set; } public string Fi

ASP.NET Web API 2 入门教程

译者:jiankunking 出处:http://blog.csdn.net/jiankunking 源码下载 HTTP不仅提供web页面服务,在构建公开服务和数据api方面,它也是一个强大的平台.HTTP简单.灵活.无处不在.几乎你能想到的所有的平台,都有一个HTTP库,因此HTTP服务可以影响到广泛的客户端,包括浏览器.移动设备,和传统的桌面应用程序. ASP.NET Web API是一个基于.NET框架用于构建Web API的框架.在本教程中,您将使用ASP.NET Web API创建一个

ASP.NET Web API 2:创建API帮助页面

     当你新建了一个web API服务之后,再建一个API帮助页面是很有好处的,这样其他开发人员就会很清楚地知道如何调用你的API接口.你可以选择自己手工建立,但是如果能自动生成岂不是更好.为了简化这项任务, ASP.NET Web API提供了一个在运行时自动生成帮助页的库.   在项目中添加帮助页,首先使用NuGet安装Microsoft.AspNet.WebApi.HelpPage库   安装成功后,启动项目有可能会报下图的异常 引起异常的原因是Microsoft.AspNet.Web