Webapi帮助页面 - 如何创建自定义数据？防御并指定需要什么？

Question

我正在查看Webapi帮助页面以生成文档,但我看到的所有教程都让我感到疑惑.

Q1.如何自己填充样本数据？根据我的理解,它会查看数据类型并根据数据类型生成一些数据.我的一些数据有特定的要求(即长度不能超过5个字符).

如何为每种方法编写自己的样本数据？

Q2如何隐藏警告信息.

我收到这条消息

无法为媒体类型'application/x-www-form-urlencoded'生成样本.不能使用格式化程序'JQueryMvcFormUrlEncodedFormatter'来编写'ProductDM'类型.

我不太确定"x-www-form-urlencoded"是什么,但如果我不支持我怎么能隐藏该消息或说"不支持"呢？

Q3如何为每个参数编写描述.在大多数情况下,很清楚它们是什么,但在某些情况下可能不是.如果它自动接受注释并将它们放在它们旁边也可以很好地显示参数A可能是选项而参数B不是.

Answer 1

Q1:你看过"Areas\HelpPage\App_Start\HelpPageConfig.cs"文件吗？您应该看到一堆注释的示例,您可以如何定义自己的样本.

例:

public static class HelpPageConfig
{
    public static void Register(HttpConfiguration config)
    {
        //// Uncomment the following to use the documentation from XML documentation file.
        //config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

        //// Uncomment the following to use "sample string" as the sample for all actions that have string as the body parameter or return type.
        //// Also, the string arrays will be used for IEnumerable<string>. The sample objects will be serialized into different media type 
        //// formats by the available formatters.
        //config.SetSampleObjects(new Dictionary<Type, object>
        //{
        //    {typeof(string), "sample string"},
        //    {typeof(IEnumerable<string>), new string[]{"sample 1", "sample 2"}}
        //});

Q2:您看到"application/x-www-form-urlencoded"mediatype的错误,因为我们使用的格式化程序只能反序列化或读取数据而无法写入.这里的错误是表明它只能写入样本,但是如果您实际上是在这种媒体类型中发送数据,则可以正确地反序列化.您可以为此媒体类型提供显式示例,而不是隐藏此部分.HelpPageConfig.cs有以下示例:

//// Uncomment the following to use "[0]=foo&[1]=bar" directly as the sample for all actions that support form URL encoded format
//// and have IEnumerable<string> as the body parameter or return type.
//config.SetSampleForType("[0]=foo&[1]=bar", new MediaTypeHeaderValue("application/x-www-form-urlencoded"), typeof(IEnumerable<string>));

问题3:有关操作参数的文档,您始终可以使用常规注释(摘要,参数等)并生成文档文件,并将其指向如下:

//// Uncomment the following to use the documentation from XML documentation file.
//config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

我们目前不支持从Data Annotations生成文档,我们目前有一个跟踪它的问题:http://aspnetwebstack.codeplex.com/workitem/877