使用XML文档扩展ApiExplorer

本文关键字：ApiExplorer 扩展 文档 XML 使用 | 更新日期: 2023-09-27 18:00:25

我已经将ASP.Net Web API帮助页面插入到我们的一个项目中，但我希望扩展从XML文档文件中读取的信息范围。

具体来说，我们的大多数端点返回的资源，除了该资源的数据外，还包括许多具有rel和uri属性的<Link>元素，以链接到其他资源和端点。我们已经扩展了XML文档，以包括关于每个资源中可能包含哪些rel的文档：

/// <summary>
/// Retrieves the X Resource
/// </summary>
/// <returns>An X</returns>
/// <resources>
/// <resource rel="self">Self reference</resource>
/// <resource rel="related-item1">Description of related item 1</resource>
/// </resources>

太好了，这一切都进入了XML文档文件。然而，IDocumentationProvider上只定义了两个方法——一个返回方法的"文档"（作为string），另一个返回参数的文档（同上）。这个接口的实现目前正在XML文档中进行搜索。

我可以尝试将额外的XML信息与实际文档一起填充到这个文档字符串中，但这感觉有点难看。我想用一个新方法来扩展接口，以检索这些更结构化的数据，并使用它来填充一个适当扩展的HelpPageApiModel。但我不知道该怎么做才是最好的。

有什么建议吗？

使用XML文档扩展ApiExplorer

在Areas''HelpPage''HelpPageConfigurationExtension.cs的已安装文件中，有以下方法，您可以获取操作的操作描述符，并根据需要自定义文档，填充"扩展"的HelpPageApiModel，也可以知道您需要修改HelpPageApiFodel.cshtml以获取"扩展"HelpPageApiNodel属性（如果有的话）。

私有静态HelpPageApiModel生成ApiModel（ApiDescription ApiDescription，HelpPageSampleGenerator sampleGenerator）

使用此方法进行自定义会更好，因为HelpPageApiModel会在第一次调用后缓存。因此，如果您在上面的方法中进行任何自定义，您将自动获得这种缓存体验。

在IDocumentationProvider上添加一个额外的方法不会有帮助，因为最终你需要以某种方式自己调用它，因为web api框架对此一无所知

如何获取操作和参数的示例如下：

 private static HelpPageApiModel GenerateApiModel(ApiDescription apiDescription, HelpPageSampleGenerator sampleGenerator)
    {
        HelpPageApiModel apiModel = new HelpPageApiModel();
        apiModel.ApiDescription = apiDescription;
        HttpActionDescriptor currentActionDescriptor = apiDescription.ActionDescriptor;
        IEnumerable<HttpParameterDescriptor> currentActionParamDescriptors = ad.GetParameters();

顺便说一句，目前存在一个错误，即帮助页面中没有显示操作的"返回"文档，但您可以通过进行一些自定义来解决此问题。姚在这里的帮助页面上有一些不错的博客。

相关文章：