从多个 .csproj 文件获取 XML 注释以填充到 Swagger UI 中

Question

我知道这里也有人问过类似的问题，但我真的很茫然。我目前有大约 5ish .csproj 文件作为 Web 应用程序的一部分，它们都包含 XML 注释。 Proj1 是目前唯一将这些评论填充到 swagger 文档中的人。我可以看到正在使用文件路径中的正确信息创建 .xml 文件（在 proj3/bin/Debug/net6.0/proj3.xml 中创建的前文件）。但是，如前所述，来自 proj1 的评论是唯一出现在 Swagger 中的评论。

我目前有一个包含以下几行的 Directory.Build.props：

<PropertyGroup Condition="'$(Configuration)'=='Debug'">
        <GenerateDocumentationFile>true</GenerateDocumentationFile>
        <NoWarn>$(NoWarn);1570;1572;1573;1587;1591;1701;1702;1705;1591</NoWarn>
     </PropertyGroup>

以及我的启动中的以下 swagger 配置：

  //  configure swagger API documentation
    builder.Services.AddSwaggerGen(config => {
       config.SwaggerDoc(appVersion, new OpenApiInfo {
           Title = "Proj1 API",
           Version = appVersion,
           Description = "REST API for control of Proj1 data"
       });
       config.SchemaFilter<ResourceSchemaFilter>();
       config.OrderActionsBy(a => $"{a.RelativePath}_{a.HttpMethod}");
       config.CustomSchemaIds(x => x.FullName);

       //  add the xml comments to the swagger generated json
       var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
       var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
       config.IncludeXmlComments(xmlPath);
    });

    //  build the application with all services

    var app = builder.Build();

    if (app.Environment.IsDevelopment()) {

       //  enable swagger documentation
       var swaggerRoute = "api-docs";
       app.UseSwagger(c => {
           c.RouteTemplate = $"{swaggerRoute}/{{documentName}}/swagger.json";
       });
       app.UseSwaggerUI(c => {
           c.SwaggerEndpoint($"/{swaggerRoute}/{appVersion}/swagger.json", $"Proj1 API {appVersion})");
           c.RoutePrefix = swaggerRoute;
       });

我尝试添加一个 $(OutputPath)$(AssemblyName).xml 行作为另一个属性组，并尝试将其作为原始项目组中 GenerateDocumentationFile 行下的一行。我还尝试将真正的 blurb 单独添加到每个 .csproj 文件中。每次，我都从仅 1 个 .csproj 文件中列出的文件中获取 Xml 注释。任何帮助将不胜感激！做精神圈算作有氧运动吗？

Answer 1

我终于找到了答案，我想我会把它留下来以防其他人发现它有用：

https://github.com/domaindrivendev/Swashbuckle.WebApi/issues/1387

基本上，使用一组 xml 文件名，然后对其执行 foreach（xmlFiles 中的 var xmlFile）以获取 xmlPath 和 .IncludeXmlComments（如果它存在于每个 .csproj 文件的路径上）。

这是我最终得到的，目前似乎正在工作：

  //  add the xml comments to the swagger generated json
    var xmlFiles = new[] {
        "Proj1.xml",
        "Proj2.xml",
        "Proj3.xml",
        "Proj4.xml"
    };
    foreach (var xmlFile in xmlFiles) {
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        if (File.Exists(xmlPath)) {
            config.IncludeXmlComments(xmlPath);
        }
    }

我可以看到对于过多的项目文件来说这可能是不合理的，但它是满足我当前需求的合适的临时解决方案。

Answer 2

您可以使用以下两行找到解决方案中的所有 XML 文件：

List<string> xmlFiles = Directory.GetFiles(AppContext.BaseDirectory,"*.xml",SearchOption.TopDirectoryOnly).ToList();
xmlFiles.ForEach(xmlFile => swaggerGenOptions.IncludeXmlComments(xmlFile)); 

如果您有 XML 文件而不是“文档注释”文件，请确保更改搜索中使用的模式 (*.xml)。