我正忙于创建 Web API(在 asp mvc4 应用程序中)。我正在使用 asp.net 站点上建议的库来生成文档 (http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages)。
我的问题是,如果我的参数是一个模型,那么我无法在生成的帮助页面中指定该模型包含哪些属性。
这是一个例子:
型号:
public class TestModel
{
property String FirstName {get;set;}
property String Surname {get; set;}
property Boolean Active {get;set;}
}
行动:
/// <summary>
/// This is a test action
/// </summary>
/// <param name="model">this is the model</param> <-- this works
/// <param name="FirstName">This is the first name </param> <-- doesn't work
/// <param name ="model.Surname">This is the surname</param> <-- doesn't work
public HttpResponseMessage Post(my.namespace.models.TestModel model)
{
...
}
只生成模型的参数。
我查看了为文档生成的 xml 文档,它确实添加了其他参数。
<member name="my.namespace.api.Post(my.namespace.models.TestModel)">
<summary>
this is a test action
</summary>
<param name="model>this is the model</param>
<param name="FirstName">This is the first name </param>
<param name="model.Surname">This is the surname</param>
</member>
但在帮助页面上它只生成参数模型。
我已经追踪到它从 xml 获取参数的方法。
Collection<ApiDescription> apiDescriptions = config.Services.GetApiExplorer().ApiDescriptions;
这位于自动生成的 HelpPageConfigurationExtentions.cs 中。
我是不是用错了方法?有人知道解决方法吗?
如有任何建议或解决方案,我们将不胜感激。
最佳答案
MVC Web API 文档功能使用反射遍历您的 API 类和方法。这将构建文档的结构,但或多或少会导致空的(和无用的)文档,除非您添加了文档注释。
文档的主体是使用 XML 文件填充的,该文件是使用///文档注释生成的,它具有必须遵循的特定结构。这意味着您不能用想要显示的内容填充 xml,它实际上必须连接到 API 中的内容,并且必须遵循类和属性的结构。
因此,在您的情况下,您不能将模型属性文档放入 api 方法中。您必须将其放入该属性所在的模型中。
型号:
public class TestModel
{
/// <summary>This is the first name </summary>
property String FirstName {get;set;}
/// <summary>This is the surname</summary>
property String Surname {get; set;}
property Boolean Active {get;set;}
}
行动:
/// <summary>
/// This is a test action
/// </summary>
/// <param name="model">this is the model</param>
public HttpResponseMessage Post(my.namespace.models.TestModel model)
{
...
}
修改帮助页面
自动生成的默认帮助页面不包含模型文档,仅记录了 api 方法。为了在您的 api 中显示有关参数的更多信息,需要进行自定义。以下说明是添加参数文档的一种方法。
在 Areas/HelpPage/Models 中创建两个新类型
public class TypeDocumentation
{
public TypeDocumentation()
{
PropertyDocumentation = new Collection<PropertyDocumentation>();
}
public string Summary { get; set; }
public ICollection<PropertyDocumentation> PropertyDocumentation { get; set; }
}
public class PropertyDocumentation
{
public PropertyDocumentation(string name, string type, string docs)
{
Name = name;
Type = type;
Documentation = docs;
}
public string Name { get; set; }
public string Type { get; set; }
public string Documentation { get; set; }
}
向 HelpPageApiModel.cs 添加新属性
public IDictionary<string, TypeDocumentation> ParameterModels{ get; set; }
创建一个新界面
internal interface IModelDocumentationProvider
{
IDictionary<string, TypeDocumentation> GetModelDocumentation(HttpActionDescriptor actionDescriptor);
}
修改XmlDocumentationProvider实现新接口(interface)
public class XmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider
{
private const string TypeExpression = "/doc/members/member[@name='T:{0}']";
private const string PropertyExpression = "/doc/members/member[@name='P:{0}']";
///...
///... existing code
///...
private static string GetPropertyName(PropertyInfo property)
{
string name = String.Format(CultureInfo.InvariantCulture, "{0}.{1}", property.DeclaringType.FullName, property.Name);
return name;
}
public IDictionary<string, TypeDocumentation> GetModelDocumentation(HttpActionDescriptor actionDescriptor)
{
var retDictionary = new Dictionary<string, TypeDocumentation>();
ReflectedHttpActionDescriptor reflectedActionDescriptor = actionDescriptor as ReflectedHttpActionDescriptor;
if (reflectedActionDescriptor != null)
{
foreach (var parameterDescriptor in reflectedActionDescriptor.GetParameters())
{
if (!parameterDescriptor.ParameterType.IsValueType)
{
TypeDocumentation typeDocs = new TypeDocumentation();
string selectExpression = String.Format(CultureInfo.InvariantCulture, TypeExpression, GetTypeName(parameterDescriptor.ParameterType));
var typeNode = _documentNavigator.SelectSingleNode(selectExpression);
if (typeNode != null)
{
XPathNavigator summaryNode;
summaryNode = typeNode.SelectSingleNode("summary");
if (summaryNode != null)
typeDocs.Summary = summaryNode.Value;
}
foreach (var prop in parameterDescriptor.ParameterType.GetProperties())
{
string propName = prop.Name;
string propDocs = string.Empty;
string propExpression = String.Format(CultureInfo.InvariantCulture, PropertyExpression, GetPropertyName(prop));
var propNode = _documentNavigator.SelectSingleNode(propExpression);
if (propNode != null)
{
XPathNavigator summaryNode;
summaryNode = propNode.SelectSingleNode("summary");
if (summaryNode != null) propDocs = summaryNode.Value;
}
typeDocs.PropertyDocumentation.Add(new PropertyDocumentation(propName, prop.PropertyType.Name, propDocs));
}
retDictionary.Add(parameterDescriptor.ParameterName, typeDocs);
}
}
}
return retDictionary;
}
}
在 GenerateApiModel 方法中将代码添加到 HelpPageConfigurationExtension
IModelDocumentationProvider modelProvider =
config.Services.GetDocumentationProvider() as IModelDocumentationProvider;
if (modelProvider != null)
{
apiModel.ParameterModels = modelProvider.GetModelDocumentation(apiDescription.ActionDescriptor);
}
修改 HelpPageApiModel.cshtml 添加到您希望显示模型文档的位置。
bool hasModels = Model.ParameterModels.Count > 0;
if (hasModels)
{
<h2>Parameter Information</h2>
@Html.DisplayFor(apiModel => apiModel.ParameterModels, "Models")
}
将 Models.cshtml 添加到 DisplayTemplates
@using System.Web.Http
@using System.Web.Http.Description
@using MvcApplication2.Areas.HelpPage.Models
@model IDictionary<string, TypeDocumentation>
@foreach (var modelType in Model)
{
<h3>@modelType.Key</h3>
if (modelType.Value.Summary != null)
{
<p>@modelType.Value.Summary</p>
}
<table class="help-page-table">
<thead>
<tr>
<th>Property</th>
<th>Description</th>
</tr>
</thead>
<tbody>
@foreach (var propInfo in modelType.Value.PropertyDocumentation)
{
<tr>
<td class="parameter-name"><b>@propInfo.Name</b> (@propInfo.Type)</td>
<td class="parameter-documentation">
<pre>@propInfo.Documentation</pre>
</td>
</tr>
}
</tbody>
</table>
}
关于c# - ASP.NET Web API 从模型生成所有参数 - 帮助页面,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/18606715/