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

最新推荐文章于 2024-10-14 22:42:36 发布
最新推荐文章于 2024-10-14 22:42:36 发布
阅读量93 收藏
点赞数
文章标签： 数据库
原文链接：http://www.cnblogs.com/cvol/p/6836226.html
版权

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 name
                genericTypeName = 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");//获取所有类似的xml
            foreach (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 name
                genericTypeName = 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

weixin_34258078
关注
java接口废弃注释_Spring Boot如何让Web API自动生成文档，并解决swagger-annotations的API注解description属性废弃的问题...
weixin_33331021的博客
02-28 2671
前后端分离的系统架构中，前端开发人员需要查看后端WEB API的文档来进行开发。采用后端API文档自动生成的方式，可以大幅提高开发效率。swagger是一个被广泛使用的文档自动生成工具，可以与多种编程语言结合使用。我们可以利用合适的jar包，让swqgger来协助java开发。本文讲述了如何把 swagger 与 Spring Boot 框架结合起来使用。我用一个项目来解释如何完成上述的目标。打开...
SpringBoot接口 - 如何生成接口文档之非侵入方式（通过注释生成）Smart-Doc？
「 虚幻私塾」
07-15 350
smart-doc是一款同时支持JAVARESTAPI和ApacheDubboRPC接口文档生成的工具，smart-doc在业内率先提出基于JAVA泛型定义推导的理念，完全基于接口源码来分析生成接口文档，不采用任何注解侵入到业务代码中。你只需要按照java-doc标准编写注释，smart-doc就能帮你生成一个简易明了的Markdown、HTML5、PostmanCollection2.0+、OpenAPI3.0+的文档。零注解、零学习成本、只需要写标准JAVA注释。...
Web API 实体显示注释
weixin_30254435的博客
02-08 267
我看园子里关于Web API的注释都是关于方法的，并没有显示实体注释的方法，今天花了一些时间搞了一下 其实注释的显示就是根据类库的XML文档文件生成的。 首先你要将所用到的类库生成XML文档文件： 在HelpPageConfig这个类中修改如下，添加多个用到的类库XML文件，原来只能添加一个 MultipleXmlDocumentationProvider代码，和XmlDocume...
【VS实践】如何在vs中自动添加注释
follow your heart
11-04 3768
前言： 之前看别人博客关于在vs中添加类注释的，今天自己看到牛腩里的讲述，也就跟着试了试，牛腩有点out了，跟着他的视频，自己还给建错了，找了找原因，也意外的开辟了新大陆！ 步骤： 1. 我的vs是2017专业版，安装是C盘里，安装目录是 2. 接着打开了这个目录 C:\Program Files (x86)\Microsoft Visual Studio\2017\Professional...
Windows命令生成文件夹目录树状结构
weixin_43628749的博客
01-09 8275
1.在电脑操作系统的开始菜单中，搜索cmd或者直接使用WIN+R快捷键组合，直接打开命令行运行程序。 2.打开命令行程序 点击确定或者使用回车键，即可打开cmd、命令行运行程序。 3.进入文件目录 找到需要生成树形结构的文件目录，如果不是在C盘，需要先进入对应大盘符（如进入D盘，使用D：+回车键，d可以不分大小写），再使用cd +目录路径的方式，进入对应的目录。 4.查看文件目录 使用dir命令，...
MVC WebApi 文档生成注释说明的方法
走错路的程序员
09-27 4832
在vs2015 里面生成的WebAPI项目 默认包含一个自动生成API说明文档的功能. 但是里面的方法注释和文档注释默认是不存在的. 百度了一下, 找到了解决方法. 生成的效果如下.首先要配置项目可以生成XML说明文档.. 右击你的项目->生成->输出->勾上 XML文档文件 然后把这个文件名放在下面的代码里.然后 在Areas/HelpPage/App_Start/HelpPageC
13.JavaScript(WebAPI) - JS api文献精解
xinhang10的博客
11-03 5862
本文章主要带大家了解了JavaScript中的主要api，已经在文章后面还为大家准备了猜数字，表白墙以及待办事项等项目来帮助大家更好地理解WebAPI。
谷粒商城笔记+踩坑（1）——架构、项目环境搭建、代码生成器
热门推荐
vincewm的博客
09-23 1万+
项目介绍、项目环境搭建、docker配置mysql,redis,jdk,maven、人人开源、快速开发、安装nodejs、逆向工程搭建，人人开源代码生成器
javadoc - Java API 文档生成器（Windows版本）
liaowenxiong的博客
09-19 1138
文章目录简介命令语法结构Javadoc Doclets术语带文档的类引用类外部引用类源文件源代码文件包注释文件概述注释文件其他未处理文件生成的文件基本内容页交叉参考页支持文件HTML 框架生成的文件结构文档注释注释源代码JAVADOC 标记@author name-text@deprecated deprecated-text@exception class-name description{@link name label}@param parameter-name description@return
使用apidoc管理RESTful风格Flask项目接口文档方法
09-20
在完成上述步骤后，运行`manage.py apidoc`命令，apidoc会根据代码中的注释生成文档，通常位于项目根目录下的`static/docs`文件夹中。 生成的接口文档页面展示了所有接口的详细信息，包括请求方法、URL、参数示例...
springboot/web项目优秀的后端接口体系，看一篇就够了
空空说技术的博客
04-16 1万+
springboot/web项目优秀的后端接口体系，看一篇就够了 项目构建-统一参数校验，统一结果响应，统一异常处理，统一错误处理，统一日志记录,统一生成api文档 1. 前言 一个后端接口大致分为四个部分组成：接口地址（url）、接口请求方式（get、post等）、请求数据（request）、响应数据（response）。 本文主要演示如何构建起一个优秀的后端接口体系，体系构建好了自然就有了规范...
【WebAPI】帮助文档添加注释
GreAmbWang的博客
11-25 809
一，右键项目属性--生成--勾选XML文档文件--将文档文件路径设置为App_Data\WebApiTest.xml 二，找到项目文件Areas\HelpPage\App_Start\HelpPageConfig.cs 三，取消Register方法里面第一行代码注释，并修改XML文档文件路径为~/App_Data/WebApiTest.xml 四，实现 在方法上添加注释 ...
MySQL数据库的详细学习步骤
2401_87352036的博客
10-11 1196
MySQL数据库的详细学习步骤可以归纳为以下几个阶段，每个阶段都包含了特定的学习内容和目标。
Java分布式锁
juanmiao的专栏
10-12 639
每种方法都有其优点和适应的场景，数据库通常简单，但可能存在性能问题，redis非常快，但需要第三方库，并且可能引入网诺问题，Zookeeper提供了更复杂的同步原语，但需要额外学习曲线。分布式锁的实现比线程锁和进程锁要复杂得多，因为它需要在网诺中的多个节点之间进行协调，以保证锁的唯一性和一致性。在实现分布式锁时，通常会有一个中心节点（或者称为锁服务），所有需要获取锁的节点都需要向这个中心节点申请。这个中心节点负责协调和管理所有节点的锁请求，确保锁的唯一性和一致性。创建临时节点，执行业务逻辑，释放锁。
mysql锁之乐观锁、悲观锁、表锁、行锁、共享锁、排他锁
最新发布
qq_68883928的博客
10-14 544
锁是计算机协调多个进程或线程并发访问某一个资源的机制，在数据库中，除传统的计算资源（CPU、RAM、I/O）的争用以外，数据也是一种供许多用户共享的资源。如何保证数据并发访问的一致性、有效性是所在有数据库必须解决的一个问题，锁冲突也是影响数据库并发访问性能的一个重要因素。从这个角度来说，锁对数据库而言显得尤其重要，也更加复杂。
SQLite数据库在Android中的应用及操作方式
Good_tea_h的博客
10-14 548
SQLite数据库在Android中的应用非常广泛，它作为一个轻量级的关系型数据库，以其高效、可靠和易于使用的特点，成为了Android平台上存储和管理数据的首选方案。以下是对SQLite数据库在Android中的应用及操作方式的详细介绍。
PostgreSQL学习笔记十：锁机制详解
软件行业技术文化交流。
10-11 1264
它通过不同级别的锁来控制对数据对象的并发访问，主要包括表级锁、行级锁、页级锁、咨询锁（Advisory Locks）以及死锁（Deadlocks）。咨询锁可以用于实现更细粒度的锁控制，例如，在不同的事务之间同步对特定资源的访问。咨询锁可以是会话级别的或事务级别的，允许用户在不同的进程或事务之间进行协调。：设计事务时，应尽量减少锁的持有时间，并避免长时间运行的事务，因为这会增加死锁的风险。这些锁可以是行级的、事务级的，或者是咨询锁（advisory locks），它们用于控制对表或行的并发访问。
数据库-01MYSQL-001MySQL知识点查漏补缺
10-12 252
mysql数据库知识点锦集
.net6webapi项目如何设置生成xml文档
09-11
在.NET 6中设置Web API项目生成XML文档，通常需要在项目文件（.csproj）中添加或配置一些参数来指定编译时生成XML注释。以下是一般步骤： 1. 打开你的.NET 6 Web API项目。 2. 找到项目文件（.csproj），它是一个XML格式的文件，可以通过VSCode、Visual Studio或其他文本编辑器打开。 3. 在`<PropertyGroup>`标签内添加以下设置： ```xml <GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn> ``` 这里`<GenerateDocumentationFile>`标签设置为`true`表示生成文档文件，而`<NoWarn>`标签的设置是为了防止编译器警告编号1591，这是与缺少XML文档相关的警告。 4. 确保你的方法、类等都有适当的XML注释，例如： ```csharp /// <summary> /// 获取用户信息 /// </summary> /// <param name="id">用户ID</param> /// <returns>用户信息</returns> [HttpGet("{id}")] public IActionResult GetUser(int id) { // 你的代码 } ``` 5. 编译项目后，会在编译输出目录下（通常是`bin\Debug\net6.0`或`bin\Release\net6.0`），找到与你的项目对应的.dll文件旁边生成一个带有`.xml`后缀的文件。 6. 如果你想要为API生成Swagger文档，通常不需要手动生成XML文件，因为Swagger工具（如Swashbuckle.AspNetCore）可以直接读取你的代码注释来自动生成API文档。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值