1.0 添加WEB API项目并按注释生成文档（多项目结构）

1.新建ASP.NET 项目，模板选择如图

2.选择Web API，并选择不进行身份验证方式

成功后我们看到这个结果。

至于其它三种身份验证方式，不太适合我的使用。而且这种方式也可以在代码里去实现身份验证，比较符合已有数据库的情况，这里不写。

3.给项目进行配置修改

3.1 修改对应项目生成路径。

这是单项目结构的，如果有多个项目并且有引用，把其它项目生成XML的地址改为接口项目的地址，当然也可以生成后再拷贝过去。

3.2修改WebAPITest\Areas\HelpPage\App_Start\HelpPageConfig.cs里面的代码。

反注释

 config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

　　里面的文档改成我们上面生成的文档名称，打开help接口就能看到注释了。

如果是引用了多个项目，就麻烦点。

先把刚刚这句改一下

 config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data")));

　　看见XmlDocumentationProvider这个类没有？转到定义过去看看,下面是原来的代码，不用看了。

 /// <summary>/// A custom <see cref="IDocumentationProvider"/> that reads the API documentation from an XML documentation file./// </summary>public class XmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider{private XPathNavigator _documentNavigator;private const string TypeExpression = "/doc/members/member[@name='T:{0}']";private const string MethodExpression = "/doc/members/member[@name='M:{0}']";private const string PropertyExpression = "/doc/members/member[@name='P:{0}']";private const string FieldExpression = "/doc/members/member[@name='F:{0}']";private const string ParameterExpression = "param[@name='{0}']";/// <summary>/// Initializes a new instance of the <see cref="XmlDocumentationProvider"/> class./// </summary>/// <param name="documentPath">The physical path to XML document.</param>public XmlDocumentationProvider(string documentPath){if (documentPath == null){throw new ArgumentNullException("documentPath");}XPathDocument xpath = new XPathDocument(documentPath);_documentNavigator = xpath.CreateNavigator();}public string GetDocumentation(HttpControllerDescriptor controllerDescriptor){XPathNavigator typeNode = GetTypeNode(controllerDescriptor.ControllerType);return GetTagValue(typeNode, "summary");}public virtual string GetDocumentation(HttpActionDescriptor actionDescriptor){XPathNavigator methodNode = GetMethodNode(actionDescriptor);return GetTagValue(methodNode, "summary");}public virtual string GetDocumentation(HttpParameterDescriptor parameterDescriptor){ReflectedHttpParameterDescriptor reflectedParameterDescriptor = parameterDescriptor as ReflectedHttpParameterDescriptor;if (reflectedParameterDescriptor != null){XPathNavigator methodNode = GetMethodNode(reflectedParameterDescriptor.ActionDescriptor);if (methodNode != null){string parameterName = reflectedParameterDescriptor.ParameterInfo.Name;XPathNavigator parameterNode = methodNode.SelectSingleNode(String.Format(CultureInfo.InvariantCulture, ParameterExpression, parameterName));if (parameterNode != null){return parameterNode.Value.Trim();}}}return null;}public string GetResponseDocumentation(HttpActionDescriptor actionDescriptor){XPathNavigator methodNode = GetMethodNode(actionDescriptor);return GetTagValue(methodNode, "returns");}public string GetDocumentation(MemberInfo member){string memberName = String.Format(CultureInfo.InvariantCulture, "{0}.{1}", GetTypeName(member.DeclaringType), member.Name);string expression = member.MemberType == MemberTypes.Field ? FieldExpression : PropertyExpression;string selectExpression = String.Format(CultureInfo.InvariantCulture, expression, memberName);XPathNavigator propertyNode = _documentNavigator.SelectSingleNode(selectExpression);return GetTagValue(propertyNode, "summary");}public string GetDocumentation(Type type){XPathNavigator typeNode = GetTypeNode(type);return GetTagValue(typeNode, "summary");}private XPathNavigator GetMethodNode(HttpActionDescriptor actionDescriptor){ReflectedHttpActionDescriptor reflectedActionDescriptor = actionDescriptor as ReflectedHttpActionDescriptor;if (reflectedActionDescriptor != null){string selectExpression = String.Format(CultureInfo.InvariantCulture, MethodExpression, GetMemberName(reflectedActionDescriptor.MethodInfo));return _documentNavigator.SelectSingleNode(selectExpression);}return null;}private static string GetMemberName(MethodInfo method){string name = String.Format(CultureInfo.InvariantCulture, "{0}.{1}", GetTypeName(method.DeclaringType), method.Name);ParameterInfo[] parameters = method.GetParameters();if (parameters.Length != 0){string[] parameterTypeNames = parameters.Select(param => GetTypeName(param.ParameterType)).ToArray();name += String.Format(CultureInfo.InvariantCulture, "({0})", String.Join(",", parameterTypeNames));}return name;}private static string GetTagValue(XPathNavigator parentNode, string tagName){if (parentNode != null){XPathNavigator node = parentNode.SelectSingleNode(tagName);if (node != null){return node.Value.Trim();}}return null;}private XPathNavigator GetTypeNode(Type type){string controllerTypeName = GetTypeName(type);string selectExpression = String.Format(CultureInfo.InvariantCulture, TypeExpression, controllerTypeName);return _documentNavigator.SelectSingleNode(selectExpression);}private static string GetTypeName(Type type){string name = type.FullName;if (type.IsGenericType){// Format the generic type name to something like: Generic{System.Int32,System.String}Type genericType = type.GetGenericTypeDefinition();Type[] genericArguments = type.GetGenericArguments();string genericTypeName = genericType.FullName;// Trim the generic parameter counts from the namegenericTypeName = genericTypeName.Substring(0, genericTypeName.IndexOf('`'));string[] argumentTypeNames = genericArguments.Select(t => GetTypeName(t)).ToArray();name = String.Format(CultureInfo.InvariantCulture, "{0}{{{1}}}", genericTypeName, String.Join(",", argumentTypeNames));}if (type.IsNested){// Changing the nested type name from OuterType+InnerType to OuterType.InnerType to match the XML documentation syntax.name = name.Replace("+", ".");}return name;}}

View Code

　　我们把它改下，整个类替换掉，没引用的自己右键引用。

 public class XmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider{// private XPathNavigator _documentNavigator;private List<XPathNavigator> _documentNavigators = new List<XPathNavigator>();private const string TypeExpression = "/doc/members/member[@name='T:{0}']";private const string MethodExpression = "/doc/members/member[@name='M:{0}']";private const string PropertyExpression = "/doc/members/member[@name='P:{0}']";private const string FieldExpression = "/doc/members/member[@name='F:{0}']";private const string ParameterExpression = "param[@name='{0}']";/// <summary>/// Initializes a new instance of the <see cref="XmlDocumentationProvider"/> class./// </summary>/// <param name="documentPath">The physical path to XML document.</param>//public XmlDocumentationProvider(string documentPath)//{//    if (documentPath == null)//    {//        throw new ArgumentNullException("documentPath");//    }//    XPathDocument xpath = new XPathDocument(documentPath);//    _documentNavigator = xpath.CreateNavigator();//}/// <summary>/// Initializes a new instance of the <see cref="XmlDocumentationProvider"/> class./// </summary>/// <param name="appDataPath">The physical path to XML document.</param>public XmlDocumentationProvider(string appDataPath){if (appDataPath == null){throw new ArgumentNullException("appDataPath");}var files = new[] { "AuthSystem.xml", "AuthSystem.SQL.xml", "AuthSystem.Common.XML" };//这里是你其它dll的说明路径，自己可以改写。例如 var files = Directory.GetFiles(appDataPath, "TLSC.*.xml");//获取所有类似的xmlforeach (var file in files){XPathDocument xpath = new XPathDocument(Path.Combine(appDataPath, file));_documentNavigators.Add(xpath.CreateNavigator());}}private XPathNavigator SelectSingleNode(string selectExpression){foreach (var navigator in _documentNavigators){var propertyNode = navigator.SelectSingleNode(selectExpression);if (propertyNode != null)return propertyNode;}return null;}public string GetDocumentation(HttpControllerDescriptor controllerDescriptor){XPathNavigator typeNode = GetTypeNode(controllerDescriptor.ControllerType);return GetTagValue(typeNode, "summary");}public virtual string GetDocumentation(HttpActionDescriptor actionDescriptor){XPathNavigator methodNode = GetMethodNode(actionDescriptor);return GetTagValue(methodNode, "summary");}public virtual string GetDocumentation(HttpParameterDescriptor parameterDescriptor){ReflectedHttpParameterDescriptor reflectedParameterDescriptor = parameterDescriptor as ReflectedHttpParameterDescriptor;if (reflectedParameterDescriptor != null){XPathNavigator methodNode = GetMethodNode(reflectedParameterDescriptor.ActionDescriptor);if (methodNode != null){string parameterName = reflectedParameterDescriptor.ParameterInfo.Name;XPathNavigator parameterNode = methodNode.SelectSingleNode(String.Format(CultureInfo.InvariantCulture, ParameterExpression, parameterName));if (parameterNode != null){return parameterNode.Value.Trim();}}}return null;}public string GetResponseDocumentation(HttpActionDescriptor actionDescriptor){XPathNavigator methodNode = GetMethodNode(actionDescriptor);return GetTagValue(methodNode, "returns");}public string GetDocumentation(MemberInfo member){string memberName = String.Format(CultureInfo.InvariantCulture, "{0}.{1}", GetTypeName(member.DeclaringType), member.Name);string expression = member.MemberType == MemberTypes.Field ? FieldExpression : PropertyExpression;string selectExpression = String.Format(CultureInfo.InvariantCulture, expression, memberName);XPathNavigator propertyNode = SelectSingleNode(selectExpression);return GetTagValue(propertyNode, "summary");}public string GetDocumentation(Type type){XPathNavigator typeNode = GetTypeNode(type);return GetTagValue(typeNode, "summary");}private XPathNavigator GetMethodNode(HttpActionDescriptor actionDescriptor){ReflectedHttpActionDescriptor reflectedActionDescriptor = actionDescriptor as ReflectedHttpActionDescriptor;if (reflectedActionDescriptor != null){string selectExpression = String.Format(CultureInfo.InvariantCulture, MethodExpression, GetMemberName(reflectedActionDescriptor.MethodInfo));return SelectSingleNode(selectExpression);}return null;}private static string GetMemberName(MethodInfo method){string name = String.Format(CultureInfo.InvariantCulture, "{0}.{1}", GetTypeName(method.DeclaringType), method.Name);ParameterInfo[] parameters = method.GetParameters();if (parameters.Length != 0){string[] parameterTypeNames = parameters.Select(param => GetTypeName(param.ParameterType)).ToArray();name += String.Format(CultureInfo.InvariantCulture, "({0})", String.Join(",", parameterTypeNames));}return name;}private static string GetTagValue(XPathNavigator parentNode, string tagName){if (parentNode != null){XPathNavigator node = parentNode.SelectSingleNode(tagName);if (node != null){return node.Value.Trim();}}return null;}private XPathNavigator GetTypeNode(Type type){string controllerTypeName = GetTypeName(type);string selectExpression = String.Format(CultureInfo.InvariantCulture, TypeExpression, controllerTypeName);return SelectSingleNode(selectExpression);}private static string GetTypeName(Type type){string name = type.FullName;if (type.IsGenericType){// Format the generic type name to something like: Generic{System.Int32,System.String}Type genericType = type.GetGenericTypeDefinition();Type[] genericArguments = type.GetGenericArguments();string genericTypeName = genericType.FullName;// Trim the generic parameter counts from the namegenericTypeName = genericTypeName.Substring(0, genericTypeName.IndexOf('`'));string[] argumentTypeNames = genericArguments.Select(t => GetTypeName(t)).ToArray();name = String.Format(CultureInfo.InvariantCulture, "{0}{{{1}}}", genericTypeName, String.Join(",", argumentTypeNames));}if (type.IsNested){// Changing the nested type name from OuterType+InnerType to OuterType.InnerType to match the XML documentation syntax.name = name.Replace("+", ".");}return name;}}

View Code

原理就是从只读一个文档改成读取多个文档。这样就能在help中看到我们写的注释（summary）了。

效果图就不贴了，免得浪费大家流量哈哈。

转载于:https://www.cnblogs.com/cvol/p/6836226.html

1.0 添加WEB API项目并按注释生成文档（多项目结构）相关推荐

newlisp 注释生成文档
最近写了一个newlisp_armory库,用来实现一些newlisp自身不支持的操作.比如跨windows和ubuntu的目录拷贝功能等. 自己用的时候,发现没有API reference文档参考, ...
Doxygen——根据代码注释生成文档的工具
文章目录 1 简介 2 安装 3 使用 3.1 注释代码 3.2 使用doxywizard生成文档 4 用例 4.1 OpenCV 4.2 Apollo 5 参考 1 简介 Doxygen是一个可以根 ...
js代码注释生成文档工具-jsdoc
需求将js和ts的代码注释生成api文档思路先将ts转成js,再统一处理js文件,用jsdoc工具来生成html文件. JsDoc 是js文档生成工具,它从javascript程序源代码中抽取类 ...
项目实战-自动生成文档工具
1.pom 文件 <dependency><groupId>cn.smallbun.screw</groupId><artifactId>screw-c ...
代码注释生成文档之Doxygen 附说明+下载连接
上个星期闫海静老师给我们讲如何使用PEAR把特定的批注转换成为说明文件,在闫海静老师给我们演示完安装和使用以后,我亲自操作了一下,感觉这东西对于我来说有点不适应,在安装过程中还需重启这让人有点无法接受 ...
python注释文档，以注释生成文档说明
Python有一种独一无二的的注释方式:使用文档字符串,文档字符串是包.模块.类或函数里的第一个语句,这些字符串可以通过对象的__doc__成员被自动提取,并且被pydoc所用. 目录 1.注释文档 ...
java接口废弃注释_Spring Boot如何让Web API自动生成文档，并解决swagger-annotations的API注解description属性废弃的问题...
前后端分离的系统架构中,前端开发人员需要查看后端WEB API的文档来进行开发.采用后端API文档自动生成的方式,可以大幅提高开发效率.swagger是一个被广泛使用的文档自动生成工具,可以与多种编程 ...
使用 apiDoc 为你的Node.js API 生成文档
翻译: 疯狂的技术宅原文:jonathas.com/documenting- 未经许可,禁止转载! 当你为其他开发人员(前端,桌面,移动等)开发 API 时,需要生成一份风格良好的文档,以便他们知道 ...
Matlab联合wps的API生成文档,让API自动生成文档
原标题:让API自动生成文档程序员最苦恼的事情莫过于写文档.由于业务口径频繁变更,因此很多接口也会频繁变更,频繁变更导致文档的维护是一件相当费时的事情,当优先级更高的事情袭来,更新文档反到成了次要工 ...

1.0 添加WEB API项目并按注释生成文档（多项目结构）

1.0 添加WEB API项目并按注释生成文档（多项目结构）相关推荐

最新文章

热门文章