当前位置：首页 > Windows程序 > 正文

【转】WebAPI使用多个xml文件生成帮助文档

2021-03-21 Windows程序

标签：

来自：一、前言

上篇有提到在WebAPI项目内，通过在Nuget里安装（Microsoft.AspNet.WebApi.HelpPage）可以根据注释生成帮助文档，查看代码实现会发现是基于解析项目生成的xml文档来作为数据源从而展示出来的。在我们的项目帮助文档需要的类（特指定义的Request和Response）与项目在同一个项目时是没有问题的，但是我们实际工作中会因为其他项目也需要引用该（Request和Response）时，我们会将其抽出来单独作为一个项目供其它调用来引用，这时，查看帮助文档不会报错，但是注释以及附加信息将会丢失，因为这些信息是我们的代码注释和数据注释（如 [Required]标识为必填），也是生成到xml文档中的信息，但因不在同一项目内，，将读取不到从而导致帮助文档无法显示我们的注释（对应的描述）和附加信息（是否必填、默认值、Range等）.

二、帮助文档注释概要

我们的注释就是帮助文档的说明或者说是描述，那么这个功能是安装了HelpPage就直接具有的吗，这里分两种方式。

1：创建项目时是直接选择的Web API，那么这时在创建初始化项目时就配置好此功能的。

2：创建项目时选择的是Empty，选择的核心引用选择Web API是不具有此功能。

对于方式1来说生成的项目代码有一部分我们是不需要的，我们可以做减法来删掉不必要的文件。

对于方式2来说，需要在Nuget内安装HelpPage，需要将文件~/Areas/HelpPage/HelpPageConfig.cs内的配置注释取消，具体的可以根据需要。

技术分享

并且设置项目的生成属性内的输出，勾选Xml文档文件，同时设置值与~/Areas/HelpPage/HelpPageConfig.cs

内的配置一致。

技术分享

并在Global.asax文件Application_Start方法注册。

AreaRegistration.RegisterAllAreas();

这时帮助文档已经可用，但却没有样式。你可以选择手动将需要的css及js拷入Areas文件夹内。并添加文件

public class BundleConfig { // 有关绑定的详细信息，请访问 ?LinkId=301862 public static void RegisterBundles(BundleCollection bundles) { bundles.Add(new ScriptBundle(‘~/bundles/jquery‘).Include( ‘~/Areas/HelpPage/Scripts/jquery-{version}.js‘)); // 使用要用于开发和学习的 Modernizr 的开发版本。然后，当你做好 // 生产准备时，请使用上的生成工具来仅选择所需的测试。 bundles.Add(new ScriptBundle(‘~/bundles/modernizr‘).Include( ‘~/Areas/HelpPage/Scripts/modernizr-*‘)); bundles.Add(new ScriptBundle(‘~/bundles/bootstrap‘).Include( ‘~/Areas/HelpPage/Scripts/bootstrap.js‘, ‘~/Areas/HelpPage/Scripts/respond.js‘)); bundles.Add(new StyleBundle(‘~/Content/css‘).Include( ‘~/Areas/HelpPage/Content/bootstrap.css‘, ‘~/Areas/HelpPage/Content/site.css‘)); } }

并在Global.asax文件Application_Start方法将其注册。

BundleConfig.RegisterBundles(BundleTable.Bundles);

最后更改~/Areas/HelpPage/Views/Shared/_Layout.cshtml 为

@using System @using System.Web.Optimization <!DOCTYPE html> <html> <head> <meta http-equiv=‘Content-Type‘ content=‘text/html; charset=utf-8‘ /> <meta charset=‘utf-8‘ /> <meta name=‘viewport‘ content=‘width=device-width‘ /> <title>@ViewBag.Title</title> @Styles.Render(‘~/Content/css‘) @Scripts.Render(‘~/bundles/modernizr‘) </head> <meta http-equiv=‘Content-Type‘ content=‘text/html; charset=utf-8‘ /> <body> <div class=‘navbar navbar-inverse navbar-fixed-top‘> <div class=‘container‘> <div class=‘navbar-header‘> <button type=‘button‘ class=‘navbar-toggle‘ data-toggle=‘collapse‘ data-target=‘.navbar-collapse‘> <span class=‘icon-bar‘></span> <span class=‘icon-bar‘></span> <span class=‘icon-bar‘></span> </button> </div> <div class=‘navbar-collapse collapse‘> <ul class=‘nav navbar-nav‘> <li>@Html.Raw(‘<a href=http://www.mamicode.com/‘/Help‘>首页</a>‘)</li> <li>@Html.Raw(‘<a href=http://www.mamicode.com/‘/PostMan‘ target=‘_blank‘>PostManFeture</a>‘)</li> </ul> </div> </div> </div> <div class=‘container body-content‘> @RenderBody() <hr /> <footer> <p>© @DateTime.Now.Year - 逗豆豆</p> </footer> </div> @Scripts.Render(‘~/bundles/jquery‘) @Scripts.Render(‘~/bundles/bootstrap‘) @RenderSection(‘scripts‘, required: false) </body> </html>

此时你看到的才会是如下的文档。

技术分享