为ASP.NET WEB API生成人性化说明文档
一、为什么要生成说明文档
我们大家都知道,自己写的API要供他人调用,就需要用文字的方式将调用方法和注意事项等写成一个文档以更好的展示我们设计时的想法和思路,便于调用者更加高效的使用我们的API。
当然,您可以不借助任何工具,自己手工写文档,然后做成chm或者html的形式交给客户,就是效率有点低,并且在API更改后有需要手工更改说明文档。
那有没有一种既方便,又能在API发生改变时,自动更新说明文档呢?答案是肯定的。
二、自动生成说明文档的具体实现
我们这里主要是将GlobalConfiguration.Configuration.Services的描述的实现换一种实现,具体是实现IDocumentationProvider这个接口,然后在调用Replace方法替换实现。
百度搜XmlCommentDocumentationProvider,有很多结果哦。这些都源于微软官方的大牛这篇文章:
下面是XmlCommentDocumentationProvider的实现:
using System.Linq;
using System.Reflection;
using System.Text.RegularExpressions;
using System.Web.Http;
using System.Web.Http.Controllers;
using System.Web.Http.Description;
using System.Web.Mvc;
using System.Xml.XPath; namespace Deepleo.API
{
/// <summary>
/// XmlCommentDocumentationProvider
/// </summary>
public class XmlCommentDocumentationProvider : IDocumentationProvider
{
readonly XPathNavigator _documentNavigator;
private const string _methodExpression = "/doc/members/member[@name='M:{0}']";
private static readonly Regex _nullableTypeNameRegex = new Regex(@"(.*\.Nullable)" + Regex.Escape("`1[[") + "([^,]*),.*"); /// <summary>
/// ctor
/// </summary>
/// <param name="documentPath">document path</param>
public XmlCommentDocumentationProvider(string documentPath)
{
XPathDocument xpath = new XPathDocument(documentPath);
_documentNavigator = xpath.CreateNavigator();
} public virtual string GetDocumentation(HttpActionDescriptor actionDescriptor)
{
XPathNavigator memberNode = GetMemberNode(actionDescriptor);
if (memberNode != null)
{
XPathNavigator summaryNode = memberNode.SelectSingleNode("summary");
if (summaryNode != null)
{
return summaryNode.Value.Trim();
}
} return "";
} public virtual string GetDocumentation(HttpParameterDescriptor parameterDescriptor)
{
ReflectedHttpParameterDescriptor reflectedParameterDescriptor = parameterDescriptor as ReflectedHttpParameterDescriptor;
if (reflectedParameterDescriptor != null)
{
XPathNavigator memberNode = GetMemberNode(reflectedParameterDescriptor.ActionDescriptor);
if (memberNode != null)
{
string parameterName = reflectedParameterDescriptor.ParameterInfo.Name;
XPathNavigator parameterNode = memberNode.SelectSingleNode(string.Format("param[@name='{0}']", parameterName));
if (parameterNode != null)
{
return parameterNode.Value.Trim();
}
}
} return "";
} private XPathNavigator GetMemberNode(HttpActionDescriptor actionDescriptor)
{
ReflectedHttpActionDescriptor reflectedActionDescriptor = actionDescriptor as ReflectedHttpActionDescriptor;
if (reflectedActionDescriptor != null)
{
string selectExpression = string.Format(_methodExpression, GetMemberName(reflectedActionDescriptor.MethodInfo));
XPathNavigator node = _documentNavigator.SelectSingleNode(selectExpression);
if (node != null)
{
return node;
}
} return null;
} private static string GetMemberName(MethodInfo method)
{
if (method.DeclaringType == null)
return string.Empty; string name = string.Format("{0}.{1}", method.DeclaringType.FullName, method.Name);
var parameters = method.GetParameters();
if (parameters.Length != )
{
string[] parameterTypeNames = parameters.Select(param => ProcessTypeName(param.ParameterType.FullName)).ToArray();
name += string.Format("({0})", string.Join(",", parameterTypeNames));
} return name;
} private static string ProcessTypeName(string typeName)
{
//handle nullable
var result = _nullableTypeNameRegex.Match(typeName);
if (result.Success)
{
return string.Format("{0}{{{1}}}", result.Groups[].Value, result.Groups[].Value);
}
return typeName;
}
}
}
这个代码是通用的,直接copy过去就ok了。
这篇博客园大牛张善友老师的博客有更详细的说明:http://www.cnblogs.com/shanyou/archive/2012/06/02/2532370.html
我主要说说后面的怎么实现:
第一步:需要在Project的Build里面打开生成xml注释文件选项,如下图所示:
第二步:改造HomeController.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using System.Web.Http.Description;
using System.Web.Http; namespace MvcApplication1.Controllers
{
public class HomeController : Controller
{
public ActionResult Index()
{
var config = GlobalConfiguration.Configuration;
config.Services.Replace(typeof(IDocumentationProvider),
new XmlCommentDocumentationProvider(HttpContext.Server.MapPath("~/bin/MvcApplication1.XML")));
var apiExplorer = config.Services.GetApiExplorer();
return View(apiExplorer);
}
}
}
代码的大意就是读取那个xml文件,然后替换掉以前的实现,换成我们的XmlCommentDocumentationProvider。
下面最后一步,修改View.
@model System.Web.Http.Description.IApiExplorer
@{
ViewBag.Title = "API说明文档";
}
<div id="body">
<section class="featured">
<div class="content-wrapper">
<hgroup class="title">
<h1>API说明文档</h1>
</hgroup>
</div>
</section>
<section class="content-wrapper main-content clear-fix">
<ul>
@foreach (var api in Model.ApiDescriptions)
{
<li>
<p>@api.HttpMethod : <b>@ViewBag.Domain@api.RelativePath</b></p>
<blockquote>
<b>Description:</b>@api.Documentation<br />
@if (api.ParameterDescriptions.Count > )
{
<b>Parameters</b>
<ul>
@foreach (var parameter in api.ParameterDescriptions)
{
<li>@parameter.Name: @parameter.Documentation {@parameter.Source}</li>
}
</ul>
}
</blockquote>
</li>
<hr/>
}
<li>
<small>来源:http://www.cnblogs.com/deepleo/p/XmlCommentDocumentationProvider.html</small>
</li>
</ul>
</section>
</div>
大功告成,在线浏览效果:http://weishangapi.deepleo.com
演示代码下载:http://files.cnblogs.com/deepleo/WebApplication1.rar
可以看到,你在代码里面的注释,会自动显示到说明文档里面,这样你就可以专注于你的API设计和实现了,无需要手工更改说明文档。
为ASP.NET WEB API生成人性化说明文档的更多相关文章
- asp.net core web api 生成 swagger 文档
asp.net core web api 生成 swagger 文档 Intro 在前后端分离的开发模式下,文档就显得比较重要,哪个接口要传哪些参数,如果一两个接口还好,口头上直接沟通好就可以了,如果 ...
- 关于ASP.NET Web Api的HelpPage文档注释问题
关于ASP.NET Web Api的HelpPage文档注释问题 以前我用微软的HelpPage来自动生成的webAPI帮助文档.在使用了一段时间后发现只能显示Controller上面写的注释文档内容 ...
- ASP.NET Core 中文文档 第二章 指南 (09) 使用 Swagger 生成 ASP.NET Web API 在线帮助测试文档
原文:ASP.NET Web API Help Pages using Swagger 作者:Shayne Boyer 翻译:谢炀(kiler) 翻译:许登洋(Seay) 对于开发人员来说,构建一个消 ...
- Swagger 生成 ASP.NET Web API
使用 Swagger 生成 ASP.NET Web API 在线帮助测试文档 原文:ASP.NET Web API Help Pages using Swagger作者:Shayne Boyer翻译: ...
- 使用ASP.NET Web API和Web API Client Gen使Angular 2应用程序的开发更加高效
本文介绍“ 为ASP.NET Web API生成TypeScript客户端API ”,重点介绍Angular 2+代码示例和各自的SDLC.如果您正在开发.NET Core Web API后端,则可能 ...
- 第二十节:Asp.Net Core WebApi生成在线文档
一. 基本概念 1.背景 使用 Web API 时,了解其各种方法对开发人员来说可能是一项挑战. Swagger 也称为OpenAPI,解决了为 Web API 生成有用文档和帮助页的问题. 它具有诸 ...
- 使用 Swagger 自动生成 ASP.NET Core Web API 的文档、在线帮助测试文档(ASP.NET Core Web API 自动生成文档)
对于开发人员来说,构建一个消费应用程序时去了解各种各样的 API 是一个巨大的挑战.在你的 Web API 项目中使用 Swagger 的 .NET Core 封装 Swashbuckle 可以帮助你 ...
- ASP.NET Web API从注释生成帮助文档
默认情况下,ASP.NET Web API不从Controller的注释中生成帮助文档.如果要将注释作为Web API帮助文档的一部分,比如在帮助文档的Description栏目中显示方法注释中的su ...
- ASP.NET Web API根据代码注释生成Help文档
使用Visual Studio新建一个ASP.NET Web API项目,直接运行,查看Help文档可以看到如下的API帮助说明 如何在Description中显示描述. 1. 打开Controlle ...
随机推荐
- es6+最佳入门实践(6)
6.Symbol用法 6.1.什么是Symbol? Symbol是es6中一种新增加的数据类型,它表示独一无二的值.es5中我们把数据类型分为基本数据类型(字符串.数字.布尔.undefined.nu ...
- 【poj1743-Musical Theme】不可重叠最长重复子串-后缀数组
http://poj.org/problem?id=1743 这题是一道后缀数组的经典例题:求不可重叠最长重复子串. 题意: 有N(1 <= N <=20000)个音符的序列来表示一首乐曲 ...
- 金山中学 rugular SRM 04 ——纪念我的第一次Ak
虽然只是一场比较简单的比赛 但奈何我也比较弱啊.... T1 一道计算概率的题目 T SRM 04 描述 给个长度为 n 的数列,每次操作能将数列打乱(RandomShuffle),问在期望下需要多少 ...
- 小白科普之JavaScript的DOM模型
微信公众号“前端大全”推送了一篇名为“通俗易懂的来讲讲DOM”的文章,把javascript原生DOM相关内容讲解的很详细.仔细读了一遍,觉得整理总结的不错,对自己也很使用,所以把内容整理过来,并根据 ...
- 以root启动pycharm
在使用scapy模块的时候提示permitted就猜想可能是权限问题.然后换成root启动啥事情都没了. 由于本机是deepin先找到pycharm.sh脚本 然后再执行sudo ./pycharm. ...
- python基础之函数(自定义函数)
函数: 函数的定义: 初中数学函数定义:一般的,在一个变化过程中,如果有两个变量x和y,并且对于x的每一个确定的值,y都有唯一确定的值与其对应,那么我们就把x称为自变量,把y称为因变量,y是x的函数. ...
- Swift, Playgrounds, and XCPlayground
http://www.codeschool.com/blog/2014/12/12/swift-playgrounds-xcplayground/ Swift, Playgrounds, and XC ...
- textbox自动提示
AutoCompleteStringCollection myCutomSource = new AutoCompleteStringCollection(); myCutomS ...
- linux环境下的GUN make学习笔记(一)
第一章:概述 1.1:make概述 在linux环境下使用make工具能够比较容易的构建一个属于自己的工程,整个工程的编译只需要一个命令就可以完成编译.连接以至于最后的执行.不过我们需要投入一些时间去 ...
- Hibernate 和 Mybatis的区别
第一方面:开发速度的对比 就开发速度而言,Hibernate的真正掌握要比Mybatis来得难些.Mybatis框架相对简单很容易上手,但也相对简陋些.个人觉得要用好Mybatis还是首先要先理解好H ...