如何在 Swagger 中处理 <see /> XML 文档标签？答案

【问题标题】：How to handle <see /> XML documentation tags in Swagger?如何在 Swagger 中处理 <see /> XML 文档标签？
【发布时间】：2023-02-15 04:09:59
【问题描述】：

我有一个带有 XML 文档的 ASP.Net Web API，包括许多 <see /> 标签。

我最近在解决方案中添加了 Swagger（Swashbuckle UI 东西），并注意到它不处理像 <see /> 这样的 XML 标签。在网上四处寻找后，我发现了这个 - https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/57，所以开发人员似乎不想解决这个问题。

有人有什么建议吗？我尝试运行一个小的 .exe 来用它们的对象名称替换生成的 XML 文件中的所有标签（例如 <see cref="MyObject"/> 变成 MyObject），但是这一直搞砸了，即使我出于某种原因手动 Swagger 也没有这样做获取更改（XML 是否已加载到内存中的某处？）

【问题讨论】：

您可以分享您的 Swashbuckle 的配置和您的 XML 文档字符串示例吗？

标签： asp.net asp.net-core swagger swagger-ui swashbuckle

【解决方案1】：

XML 文档 cmets 生成 into a file，与同一文件夹中的程序集同名（通常）。您可以使用 XDocument 和相关类解析该文件，然后使用 schema filter (ISchemaFilter) 在 Swashbuckle 公开的 Open API schema 上设置适当的属性。

我不确定哪种模式元素适合“另见”或“相关资源”功能。您需要对此进行调查（可能是 ASP.NET Core's Open API implementation 中的自定义属性，或者通过将文本附加到描述属性）。

至于

XML 是否加载到内存中的某处？

是的。 Swashbuckle 本身解析此 XML 以完成它当前所做的所有工作。粗略地说，它将其构建到一个文档对象模型 (DOM) 中，该模型建立在上面提到的 Microsoft 的 Open API 实现之上。使用架构过滤器将使您能够访问该 DOM。

【讨论】：

这让我走上了正确的轨道，仍然在搞乱，目前代码很糟糕，但当我整理好后我会发布，感谢您的帮助！

【解决方案2】：

根据 Kit 的建议，我找到了一种检索和更改文档的方法，但需要一种解析 XML 标记的方法。我找到了 this，虽然它指的是 HTML，但也删除了 XML 标签。

因此，按照要求的顺序：

我有一个通用的 Utilities 类，我将上面的 HtmlAgilityPack 代码放在其中（尽管我调用了 RemoveXMLTags 方法）

添加了一个新的 XmlDocumentFilter 类，如下所示：

public class XmlDocumentFilter : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        foreach (var path in swaggerDoc.Paths)
        {
            foreach (var operation in path.Value.Operations)
            {
                operation.Value.Description = Utilities.RemoveXMLTags(operation.Value.Description);

                operation.Value.Summary = Utilities.RemoveXMLTags(operation.Value.Summary);

                if (operation.Value.RequestBody != null)
                {
                    operation.Value.RequestBody.Description = Utilities.RemoveXMLTags(operation.Value.RequestBody.Description);
                }

                foreach (var parameter in operation.Value.Parameters)
                {
                    parameter.Description = Utilities.RemoveXMLTags(parameter.Description);
                }
            }
        }
    }
}

将以下内容添加到我的 Startup 类中：

services.AddSwaggerGen(setupAction =>
    {
        setupAction.SwaggerDoc(
            "MyAppAPIDocumentation",
            new OpenApiInfo() { Title = "MyApp API", Version = "1" });

        var xmlDocumentationFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlDocumentationFullPath = Path.Combine(AppContext.BaseDirectory, xmlDocumentationFile);

        setupAction.IncludeXmlComments(xmlDocumentationFullPath);
        setupAction.DocumentFilter<XmlDocumentFilter>();
    });

利润

【讨论】：