ASP.NET API Helper Page 创建并生成相关帮助文档

• 创建API项目

• 修改原工程文件，该行为是为了避免和引入第三方API工程文件冲突

• 修改发布设置

• 引入需要生成文档的相关文件，将第三方API依赖的相关文件（XML文件非常重要，是注释显示的关键），复制到文档工程的bin目录下，为避免引用依赖出错，尽可能全拷贝，宁多勿少

• 修改XML文件读取逻辑，可读取多个XML文件（原有工程中只能读取单个XML文件），添加类MultiXmlDocumentationProvider，代码如下：

 

public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider

{

/*********

** Properties

*********/

/// <summary>The internal documentation providers for specific files.</summary>

private readonly XmlDocumentationProvider[] Providers;

/*********

** Public methods

*********/

/// <summary>Construct an instance.</summary>

/// <param name="paths">The physical paths to the XML documents.</param>

public MultiXmlDocumentationProvider(params string[] paths)

{

this.Providers = paths.Select(p => new XmlDocumentationProvider(p)).ToArray();

}

/// <summary>Gets the documentation for a subject.</summary>

/// <param name="subject">The subject to document.</param>

public string GetDocumentation(MemberInfo subject)

{

return this.GetFirstMatch(p => p.GetDocumentation(subject));

}

/// <summary>Gets the documentation for a subject.</summary>

/// <param name="subject">The subject to document.</param>

public string GetDocumentation(Type subject)

{

return this.GetFirstMatch(p => p.GetDocumentation(subject));

}

/// <summary>Gets the documentation for a subject.</summary>

/// <param name="subject">The subject to document.</param>

public string GetDocumentation(HttpControllerDescriptor subject)

{

return this.GetFirstMatch(p => p.GetDocumentation(subject));

}

/// <summary>Gets the documentation for a subject.</summary>

/// <param name="subject">The subject to document.</param>

public string GetDocumentation(HttpActionDescriptor subject)

{

return this.GetFirstMatch(p => p.GetDocumentation(subject));

}

/// <summary>Gets the documentation for a subject.</summary>

/// <param name="subject">The subject to document.</param>

public string GetDocumentation(HttpParameterDescriptor subject)

{

return this.GetFirstMatch(p => p.GetDocumentation(subject));

}

/// <summary>Gets the documentation for a subject.</summary>

/// <param name="subject">The subject to document.</param>

public string GetResponseDocumentation(HttpActionDescriptor subject)

{

return this.GetFirstMatch(p => p.GetDocumentation(subject));

}

/*********

** Private methods

*********/

/// <summary>Get the first valid result from the collection of XML documentation providers.</summary>

/// <param name="expr">The method to invoke.</param>

private string GetFirstMatch(Func<XmlDocumentationProvider, string> expr)

{

return this.Providers

.Select(expr)

.FirstOrDefault(p => !String.IsNullOrWhiteSpace(p));

}

}

修改HelpPageConfig.cs文件中的调用：

 

• 错误：【A model description could not be created. Duplicate model name '{0}' was found for types '{1}' and '{2}'. Use the [ModelName] attribute to change the model name for at least one of the types so that it has a unique name.】处理

修改ModelNameHelper.cs文件

• 生成后的API文档，Description中的No documentation available.是因为API在编写的时候没有添加三行注释造成的，编写代码的时候规范必不可少

• 过滤不需要生成文档的控制器，需要在控制器上添加过滤标签[ApiExplorerSettings(IgnoreApi = true)]

 

自此生成第三方API文档搭建完成，感谢项目组内小何对页面也进行了美化，效果如下：