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

标签：

一、前言

上篇有提到在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>

<title>@ViewBag.Title</title>

@Styles.Render("~/Content/css")

@Scripts.Render("~/bundles/modernizr")

</head>

<body>

秒客网

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

相关文章