ASP.NET Web API编程——构建api帮助文档
1 概要
创建ASP.NET Web Api 时模板自带Help Pages框架。
2 问题
1)使用VS创建Web Api项目时,模板将Help Pages框架自动集成到其中,使得Web Api项目引入了MVC框架开发包,使得项目看起来杂乱。
2)自带的Help Pages框架无法针对Odata控制器生成API文档。
3 问题解决方案
1)独立Help Pages项目,以插件形式添加服务
步骤1,添加类ServiceAssembliesResolver,获得服务集
/// <summary>
/// 获取插件服务
/// </summary>
public class ServiceAssembliesResolver : DefaultAssembliesResolver
{
public override ICollection<Assembly> GetAssemblies()
{
//获得已有的服务
ICollection<Assembly> baseAssemblies = base.GetAssemblies();
//初始化
List<Assembly> assemblies = new List<Assembly>(baseAssemblies);
//服务插件dll路径
var path = WebConfigSetting.ServicesLocation;
//加载每一个服务插件
foreach (string file in Directory.GetFiles(path, "*.dll"))
{
var controllersAssembly = Assembly.LoadFrom(file);
assemblies.Add(controllersAssembly);
} return assemblies;
}
}
步骤2,替换现有服务
在WebApiConfig.Register方法中添加代码
config.Services.Replace(typeof(IAssembliesResolver), new ServiceAssembliesResolver());
完整代码如下:
namespace HY_WebApi.HelpPages
{
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
// Web API 配置和服务
config.Services.Replace(typeof(IAssembliesResolver), new ServiceAssembliesResolver()); // Web API 路由
config.MapHttpAttributeRoutes(); config.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{action}/{id}",
defaults: new { id = RouteParameter.Optional }
); //OData路由,将路由名称设置为控制器(去掉Controller)名称,以便生成Api帮助文档
config.MapODataServiceRoute(
routeName: "ODataSearch",
routePrefix: "odata",
model: GetEdmModel(),
batchHandler: new DefaultODataBatchHandler(GlobalConfiguration.DefaultServer)); }
private static IEdmModel GetEdmModel()
{
ODataConventionModelBuilder builder = new ODataConventionModelBuilder();
builder.EntitySet<Institution>("ODataSearch"); builder.Namespace = "Search";
//builder.EntityType<Institution>().Collection.Function("GetByIdEq2").Returns<string>();
return builder.GetEdmModel();
} public class Institution
{
public int Id { get; set; }
public string Name { get; set; }
public string Address { get; set; }
}
}
}
步骤3,添加MultiXmlDocumentationProvider类,读取多个XML文档
/// <summary>
/// 加载目录下的所有Xml文档
/// </summary>
public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider
{
private IList<XmlDocumentationProvider> _documentationProviders; public MultiXmlDocumentationProvider(string xmlDocFilesPath)
{
_documentationProviders = new List<XmlDocumentationProvider>(); foreach (string file in Directory.GetFiles(xmlDocFilesPath, "*.xml"))
{
_documentationProviders.Add(new XmlDocumentationProvider(file));
}
} public string GetDocumentation(HttpParameterDescriptor parameterDescriptor)
{
return _documentationProviders.Select(x => x.GetDocumentation(parameterDescriptor)).FirstOrDefault(x => !string.IsNullOrEmpty(x));
} public string GetDocumentation(Type type)
{
return _documentationProviders.Select(x => x.GetDocumentation(type)).FirstOrDefault(x => !string.IsNullOrEmpty(x));
} //成员导航
public string GetDocumentation(MemberInfo member)
{
return _documentationProviders
.Select(x => x.GetDocumentation(member))
.FirstOrDefault(x => !string.IsNullOrWhiteSpace(x));
} //action 描述
public string GetDocumentation(HttpActionDescriptor actionDescriptor)
{
return _documentationProviders.Select(x => x.GetDocumentation(actionDescriptor)).FirstOrDefault(x => !string.IsNullOrEmpty(x));
} //Controller 描述
public string GetDocumentation(HttpControllerDescriptor controllerDescriptor)
{
return _documentationProviders.Select(x => x.GetDocumentation(controllerDescriptor)).FirstOrDefault(x => !string.IsNullOrEmpty(x));
} public string GetResponseDocumentation(HttpActionDescriptor actionDescriptor)
{
return _documentationProviders.Select(x => x.GetDocumentation(actionDescriptor)).FirstOrDefault(x => !string.IsNullOrEmpty(x)); }
}
步骤4,使用MultiXmlDocumentationProvider
将config.SetDocumentationProvider(new MultiXmlDocumentationProvider(WebConfigSetting.ServicesLocation));添加到Register方法中
步骤5,创建服务插件文件夹,将服务插件及其XML文档放在文件夹中。
2)重构ApiExplorer,获得Odata控制器的API文档
步骤1,重构ApiExplorer
public class CustomApiExplorer : ApiExplorer
{
private HttpConfiguration configuration;
public CustomApiExplorer(HttpConfiguration configuration)
: base(configuration)
{
this.configuration = configuration;
}
public override bool ShouldExploreController(string controllerVariableValue, HttpControllerDescriptor controllerDescriptor, IHttpRoute route)
{
if (controllerDescriptor == null)
{
throw new ArgumentNullException("controllerDescriptor");
} if (route == null)
{
throw new ArgumentNullException("route");
}
var c = controllerDescriptor.ControllerName;
//获得OData路由
IEdmModel edm = EdmModelCreater.GetEdmModel();
List<string> collectionFromEdms = new List<string>();
foreach (var item in edm.EntityContainer.Elements)
{
collectionFromEdms.Add(item.Name);
} //如果是Odata控制器,那么忽略ApiExplorerSettingsAttribute
ApiExplorerSettingsAttribute setting = controllerDescriptor.GetCustomAttributes<ApiExplorerSettingsAttribute>().FirstOrDefault();
bool isOdataController = collectionFromEdms.Contains(controllerDescriptor.ControllerName);
bool isBaseApi = controllerDescriptor.ControllerName != "BaseApi";
return isBaseApi||isOdataController ||
((setting == null || !setting.IgnoreApi) && MatchRegexConstraint(route, RouteValueKeys.Controller, controllerVariableValue));
} public override bool ShouldExploreAction(string actionVariableValue, HttpActionDescriptor actionDescriptor, IHttpRoute route)
{
if (actionDescriptor == null)
{
throw new ArgumentNullException("actionDescriptor");
} if (route == null)
{
throw new ArgumentNullException("route");
} //获得OData路由
IEdmModel edm = EdmModelCreater.GetEdmModel();
List<string> collectionFromEdms = new List<string>();
foreach (var item in edm.EntityContainer.Elements)
{
collectionFromEdms.Add(item.Name);
} //如果是Odata控制器,那么忽略ApiExplorerSettingsAttribute
ApiExplorerSettingsAttribute setting = actionDescriptor.ControllerDescriptor.GetCustomAttributes<ApiExplorerSettingsAttribute>().FirstOrDefault();
bool isOdataController = collectionFromEdms.Contains(actionDescriptor.ControllerDescriptor.ControllerName);
bool isBaseApi = actionDescriptor.ControllerDescriptor.ControllerName != "BaseApi";
return isBaseApi||isOdataController ||
((setting == null || !setting.IgnoreApi) && MatchRegexConstraint(route, RouteValueKeys.Action, actionVariableValue));
} private static bool MatchRegexConstraint(IHttpRoute route, string parameterName, string parameterValue)
{
IDictionary<string, object> constraints = route.Constraints;
if (constraints != null)
{
object constraint;
if (constraints.TryGetValue(parameterName, out constraint))
{
// treat the constraint as a string which represents a Regex.
// note that we don't support custom constraint (IHttpRouteConstraint) because it might rely on the request and some runtime states
string constraintsRule = constraint as string;
if (constraintsRule != null)
{
string constraintsRegEx = "^(" + constraintsRule + ")$";
return parameterValue != null && Regex.IsMatch(parameterValue, constraintsRegEx, RegexOptions.CultureInvariant | RegexOptions.IgnoreCase);
}
}
} return true;
}
}
添加RouteValueKeys类
internal static class RouteValueKeys
{
// Used to provide the action and controller name
public const string Action = "action";
public const string Controller = "controller";
}
添加OdataRelativePath类
public static class OdataRelativePath
{
public static void GetOdataRelativePath(CustomApiExplorer customApiExplorer, HttpConfiguration configuration)
{
IEdmModel edm = EdmModelCreater.GetEdmModel();
List<string> collectionFromEdms = new List<string>();
foreach(var item in edm.EntityContainer.Elements)
{
collectionFromEdms.Add(item.Name);
}
Collection<ApiDescription> apiColloction = customApiExplorer.ApiDescriptions;
foreach (ApiDescription api in apiColloction)
{
string controllerName = api.ActionDescriptor.ControllerDescriptor.ControllerName;
//去掉Odata中控制器的版本号
var controllerSelector = configuration.Services.GetService(typeof(IHttpControllerSelector)) as VersionControllerSelector;
string oldString = controllerSelector.RouteVersionSuffixMapping.First(m => m.Key.Contains("OdataRouteVersioning")).Value;
controllerName = controllerName.Replace(oldString, "");
if (collectionFromEdms.Contains(controllerName))
{
string actionName = api.ActionDescriptor.ActionName;
var parameters = api.ActionDescriptor.GetParameters();
string paramStr = null;
foreach (var parameter in parameters)
{
var t = parameter.ParameterType;
if (parameter.ParameterType.IsClass)
{
continue;
}
if (paramStr != null)
{
paramStr = string.Format("{0}&({1}={1})", paramStr, parameter.ParameterName);
}
else
{
paramStr = string.Format("({0}={0})", parameter.ParameterName);
}
}
api.RelativePath = string.Format("{0}/{1}/{2}/Service.{3}{4}", "odata", "{Version}", controllerName, actionName, paramStr);
}
else
{
Regex reg=new Regex("[0-9]");
Match match = reg.Match(api.RelativePath);
if(match.Success)
{
api.RelativePath = api.RelativePath.Replace(string.Format("V{0}",match.Value),"");
}
}
}
}
}
步骤2;根据OData路由拼出api的URI
使用OdataRelativePath.GetOdataRelativePath方法修改ApiExplorer.ApiDescriptions中的URI
例如在控制器中
public ActionResult Index()
{
ViewBag.DocumentationProvider = Configuration.Services.GetDocumentationProvider();
CustomApiExplorer customApiExplorer = new CustomApiExplorer(Configuration);
OdataRelativePath.GetOdataRelativePath(customApiExplorer,Configuration);
Collection<ApiDescription> apiDescriptions = new Collection<ApiDescription>();
List<ApiDescription> list = new List<ApiDescription>();
foreach (ApiDescription ad in customApiExplorer.ApiDescriptions)
{
if (ad.ActionDescriptor.ControllerDescriptor.ControllerName != "Metadata" && ad.ActionDescriptor.ActionName != "ToJson")
{
list.Add(ad);
}
}
list = list.OrderBy(m => m.ActionDescriptor.ControllerDescriptor.ControllerName).ToList();
list.ForEach(m =>
{
apiDescriptions.Add(m);
});
return View(apiDescriptions);
}
注意:配置Odata路由时,将路由名称配置为控制器名称(不含Controller字符串),并且编写服务程序时,遵循一个实体对应一个控制器,对应一个Odata路由。
-----------------------------------------------------------------------------------------
转载与引用请注明出处。
时间仓促,水平有限,如有不当之处,欢迎指正。
ASP.NET Web API编程——构建api帮助文档的更多相关文章
- Struts2 API的chm格式帮助文档制作教程
Struts2 API的chm格式帮助文档制作教程 在SSH三个框架中,Struts2的API文档是最难做的,这里所说的格式是chm格式的,chm的格式很方便,Hibernate API文档和Spri ...
- Android BLE与终端通信(五)——Google API BLE4.0低功耗蓝牙文档解读之案例初探
Android BLE与终端通信(五)--Google API BLE4.0低功耗蓝牙文档解读之案例初探 算下来很久没有写BLE的博文了,上家的技术都快忘记了,所以赶紧读了一遍Google的API顺便 ...
- api接口测试工具和接口文档管理工具
api接口测试工具和接口文档管理工具 1.postman(https://www.getpostman.com) Postman 是一个很强大的 API调试.Http请求的工具.她可是允许用户发送任何 ...
- 转:ASP.NET MVC 将IList<T>导出Excel文档的泛型类
/// <summary> /// 提供将泛型集合数据导出Excel文档. /// </summary> /// <typeparam name="T" ...
- Jenkins构建项目帮助文档
Jenkins构建项目帮助文档 主要步骤 一.配置jdk 1.1. 下载jdk,安装到自己电脑磁盘的Java目录下(比如:D:\Java\jdk). 1.2. Jdk环境变量的配置: 1. 鼠 ...
- ASP.NET Web API从注释生成帮助文档
默认情况下,ASP.NET Web API不从Controller的注释中生成帮助文档.如果要将注释作为Web API帮助文档的一部分,比如在帮助文档的Description栏目中显示方法注释中的su ...
- 开发API完成,写个文档
Jira对接Prism开发API指南 部门 证系统运维团队 文档制作人 陈刚() 时间 2017-04-05 版本 第一版 目录 目的... 1 通例:... 1 认证... 2 新建版本单... 2 ...
- 使用Swashbuckle构建RESTful风格文档
本次和大家分享的是Swagger to WebApi的nuget包Swashbuckle:因为项目需要统一api文档的风格,并要支持多种开发语言(C#,java,python),所以首先想到的是swa ...
- springmvc+swagger构建Restful风格文档
本次和大家分享的是java方面的springmvc来构建的webapi接口+swagger文档:上篇文章分享.net的webapi用swagger来构建文档,因为有朋友问了为啥.net有docpage ...
随机推荐
- SpringCloud实战之初级入门(一)— eureka注册中心
目录 写在前面 1.资料目录 2.环境介绍 3.eureka注册中心 3.1 创建工程 3.2 启动工程 5.eureka注册中心集群高可用 6.结语 7.一点点重要的事情 写在前面 我在软件行业浸泡 ...
- 一些在线开发手册api文档收藏
java JavaSE8 api:https://docs.oracle.com/javase/8/docs/api/ JavaSE7 api:http://docs.oracle.com/javas ...
- 流畅的python和cookbook学习笔记(二)
1.元组拆包和解压序列赋值 任何的序列 (或者是可迭代对象) 可以通过一个简单的赋值语句解压并赋值给多个 变量.唯一的前提就是变量的数量必须跟序列元素的数量是一样的. 1.平行赋值: >> ...
- Mysql根据经纬度筛选数据
创建位置表,并且插入测试数据 /* Navicat MySQL Data Transfer Source Server : localhost Source S ...
- Heka 最简单例子
技术人员学习都是从简单例子开始的, Heka的应用也是从简单开始的. 需求: 监控一个日志文件的内容, 在标准输出显示出来. 操作步骤: 使用下载好或者编译好的 heka 已经编译好的 rel ...
- PAT 1082. Read Number in Chinese
#include <cstdio> #include <cstdlib> #include <string> #include <vector> #in ...
- vue-构建项目相关事项
安装 :vue-cli npm install -g vue-cli 使用webpack 打包 vue 項目的創建: vue init webpack 項目名子 生產基本的項目結構后 進入到項目目錄 ...
- JavaScript练习笔记整理·1 - 6.23
练习平台Codewars地址:https://www.codewars.com/ 欢迎和大家一起来讨论~╭( ・ㅂ・)و ̑̑ 基础练习(1): 我的解答为: class SmallestIn ...
- 颜色矩原理及Python实现
原理 颜色矩(color moments)是由Stricker 和Orengo所提出的一种非常简单而有效的颜色特征.这种方法的数学基础在于图像中任何的颜色分布均可以用它的矩来表示.此外,由于颜色分布信 ...
- linux下网络编程学习——入门实例ZZ
http://www.cppblog.com/cuijixin/archive/2008/03/14/44480.html 是不是还对用c怎么实现网络编程感到神秘莫测阿,我们这里就要撕开它神秘的面纱, ...