Asp.net Web Api開發Help Page 新增對資料模型生成註釋的配置和擴充套件
阿新 • • 發佈:2018-11-26
在使用webapi框架進行介面開發的時候,編寫文件會需要與介面同步更新,如果採用手動式的更新的話效率會非常低。webapi框架下提供了一種自動生成文件的help Page頁的功能。
但是原始版本的效果不是很好,最重要的一點是沒有對資料模型的詳細註解提供展示。這種請情況下需要我們自己對其進行拓展,方便顯示出介面和資料模型註解,在將介面提供給其他人使用時提高可讀性。
下面先上兩份效果圖
在這裡講一下最重要的兩個步驟
1:重寫拓展一個XmlDocumentationProvider類
/// <summary>A custom /// <see cref="IDocumentationProvider"/> /// that reads the API documentation from a collection of XML documentation files. /// </summary> 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)); } }
2改寫 HelpPageConfig 檔案
然後指定下xml的生成目錄 開啟專案屬性設定 即可 然後執行 就是一個可以顯示註釋的良好頁面了