标签：ppa rect pat cto fun exception ams mst gis
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路由。
-----------------------------------------------------------------------------------------
转载与引用请注明出处。
时间仓促，水平有限，如有不当之处，欢迎指正。
标签：ppa rect pat cto fun exception ams mst gis
原文地址：http://www.cnblogs.com/hdwgxz/p/7898983.html
