Asp.net WebApi添加帮助文档
一、创建一个空的WebApi站点
二、新增一个名为Test的API控制器,实现部分方法(方法和类要添加文档说明注释)
1. 添加一个用户数据模型UserInfo.cs,代码如下:
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
/// <summary> /// 用户信息 /// </summary> public class UserInfo { /// <summary> /// 用户ID /// </summary> public int ID { get; set; } /// <summary> /// 用户名称 /// </summary> public string UserName { get; set; } /// <summary> /// 用户年龄 /// </summary> public int Age { get; set; } }
2. TestController.cs文件中的代码如下:(控制器中使用了用户数据模型,故要在控制器的顶部将用户数据模型的命名空间引用进来)
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
public class TestController : ApiController { /// <summary> /// 添加用户 /// </summary> /// <param name="model">实体</param> /// <returns>返回提示信息</returns> [HttpPost] public string Add(UserInfo model) { return "添加成功"; } /// <summary> /// 删除用户 /// </summary> /// <param name="id">用户ID</param> /// <returns>返回提示信息</returns> public string Delete(int id) { return "删除成功"; } /// <summary> /// 更新用户 /// </summary> /// <param name="id">用户ID</param> /// <returns>返回提示信息</returns> public string Update(int id) { return "更新成功"; } /// <summary> /// 获取用户列表 /// </summary> /// <returns>返回用户列表集合</returns> [HttpGet] public List<UserInfo> Get() { List<UserInfo> list = new List<UserInfo>(); list.Add(new UserInfo { ID = 0, UserName = "小明", Age = 18 }); list.Add(new UserInfo { ID = 1, UserName = "小红", Age = 22 }); return list; } }
以上的类中都对类和方法以及属性添加了说明,使用文档注释///进行说明
3. 修改以下API路由
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
public static class WebApiConfig { public static void Register(HttpConfiguration config) { // Web API 配置和服务 // Web API 路由 config.MapHttpAttributeRoutes(); config.Routes.MapHttpRoute( name: "DefaultApi", //routeTemplate: "api/{controller}/{id}", routeTemplate: "api/{controller}/{action}/{id}", //这里路由添加action项,具体的使用看项目 defaults: new { id = RouteParameter.Optional } ); } }
三、上面接口已经实现了,下面添加API帮助页
1. 在nuget中添加Microsoft.AspNet.WebApi.HelpPage
2. 安装完之后,工程文件中会多出一个Area的文件夹,文件夹下有一个HelpPage文件夹
3. 注册Area
打开Global.asax文件,在Application_Start方法中添加Area的注册
![](https://images.cnblogs.com/OutliningIndicators/ContractedBlock.gif)
using System; using System.Collections.Generic; using System.Linq; using System.Web; using System.Web.Http; using System.Web.Mvc; using System.Web.Routing; namespace WebApiHelpPage { public class WebApiApplication : System.Web.HttpApplication { protected void Application_Start() { AreaRegistration.RegisterAllAreas(); //注册Area GlobalConfiguration.Configure(WebApiConfig.Register); } } }
4. 设置输出XML文件,如:这里我的XML输入文件设置在App_Data文件夹下,命名为MyAPI.XML。(这个文件地址,在后面会涉及用到,需要注意)
右击工程文件》属性》生成》输出》XML文档文件
5. HelpPageConfig启用SetDocumentationProvider
在HelpPageConfig类的Register方法中,添加以下代码
config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/MyAPI.XML")));
6. 重新生成项目,在站点的域名后添加/help 就可以访问到api的帮助页了
四、调用API接口
在浏览器中输入 http://localhost:21764/api/test/get 就可以调用上面的获取用户列表的接口了。