WebAPI接口帮助文档详细说明

前段时间有个项目用到了webapi，不得不说，webapi的自动生成的接口帮助文档实在是太方便了。不过好用归好用，默认生成的文档还是有些小小的问题的，还需要稍微改良一下。

使用webapi生成的接口文档默认是这样子的，虽然我在接口和参数中都加了注释，然而并没有显示：

为了将注释显示出来，需要如下几个步骤：

1.必须先生成接口和Model参数的xml文档。方法如下：
分别选中Model项目和API项目【属性-生成-输出-XML文档文件】（其中Model项目XML为接口参数说明，API项目XML为接口方法说明），如下图所示：

2.生成好xml文档后，要配置到接口的帮助文档中，方法如下：
打开Areas/HelpPage/App_Start/HelpPageConfig.cs，注意看，原始文件中有如下一句代码：
//config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));
该代码默认被注释了。按理说，放开这句注释，然后把xml移到对应路径下就可以了。但是~~~我们有两个xml文件，所以此方法直接忽略。复制下列代码到Register方法中：

       var xmlPaths = new[]
{HttpContext.Current.Server.MapPath("~/bin/MyLittleSecret.Model.xml"),HttpContext.Current.Server.MapPath("~/bin/MyLittleSecret.API.xml")
};config.SetDocumentationProvider(new XmlDocumentationProvider(xmlPaths));

红框内路径改为你自己的项目路径，记得我们之前是将xml文件直接生在在bin路径下，如果你是放到了其他路径下，记得修改这里对应的路径。

3.添加完之后会有如下错误：

定位到XmlDocumentationProvider的构造函数，发现如下：

原来该构造函数只处理接受单个xml路径的方法，如果要添加多个xml文件，就必须修改构造函数，或者直接添加一个参数为string[]的重构方法。
代码如下：

public XmlDocumentationProvider(IEnumerable documentPaths)
{if (documentPaths == null){throw new ArgumentNullException(nameof(documentPaths));}XDocument fullDocument = null;foreach (var documentPath in documentPaths){if (documentPath == null){throw new ArgumentNullException(nameof(documentPath));}if (fullDocument == null){using (var stream = File.OpenRead(documentPath)){fullDocument = XDocument.Load(stream);}}else{using (var stream = File.OpenRead(documentPath)){var additionalDocument = XDocument.Load(stream);fullDocument?.Root?.XPathSelectElement("/doc/members").Add(additionalDocument?.Root?.XPathSelectElement("/doc/members").Elements());}}}_documentNavigator = fullDocument?.CreateNavigator();
}

加完之后重新运行，就可以显示出API的接口描述了。

当当当~~~完成！这样一来，整个接口文档描述就相当清晰了。

本文来自互联网用户投稿，文章观点仅代表作者本人，不代表本站立场，不承担相关法律责任。如若转载，请注明出处。 如若内容造成侵权/违法违规/事实不符，请点击【内容举报】进行投诉反馈！