XML注释文件找不到 - Swagger

Question

这绝对是让人抓狂的问题。如标题所示，我只是想使用Swagger显示从XML文件中提取的评论。

我已经按照Swagger文档中的步骤操作了，但却不起作用。希望您能指点我走向正确的方向。

已执行以下步骤：

确保文件存在：

配置SwaggerConfig.cs

我尝试过更改路径：@"bin/....xml"

但什么都没有起作用。

错误信息“找不到文件”：

请问有谁能指点我走向正确的方向吗？

谢谢！

- Tez Wingfield

---

它能在没有文件的情况下工作吗？尝试更改名称。 - Amanullah Tariq

Answer 1

.NET Core 3.0中

<GenerateDocumentationFile>true</GenerateDocumentationFile>

在.csproj文件的PropertyGroup标签中。

- mosess

---

如何删除文件 - 如果仅用于测试目的？ - nelion

在.NET 7.0中仍然有效。 - Gerard Jaryczewski

Answer 2

这是我在 .Net Core 2.2 中需要的步骤:

将以下内容放入Startup.cs中：

    public void ConfigureServices(IServiceCollection services)
    {

        ...

        // Register the Swagger generator, defining 1 or more Swagger documents
        services.AddSwaggerGen(c =>
            {
                ...

                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath);
            });
    }

编辑您的.csproj文件并添加/更改这些节点：

  <PropertyGroup>
    ...
    <!-- 
    Make sure documentation XML is also included when publishing (not only when testing)
    see https://github.com/Azure/service-fabric-issues/issues/190
    -->
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    ...
    <DocumentationFile>bin\$(Configuration)\$(AssemblyName).xml</DocumentationFile>
  </PropertyGroup>

- Jpsy

---

使用 .Net 3.1 和 Swashbuckle 5.6.2...我所需要的只是属性组更改。 - Chris Catignani

Answer 3

根据异常信息，应用程序在项目的基础目录中查找XML文件，而不是“bin”文件夹中。为什么应用程序要在基础目录中搜索呢？看一下这些代码行：

var baseDirectory = AppDomain.CurrentDomain.BaseDirectory;
var commentsFileName = Assembly.GetExecutingAssembly().GetName().Name + ".XML";//"G2F.Collective.Api.XML"
var commentsFile = Path.Combine(baseDirectory, commentsFileName);

评论文件的名称是通过基础目录和带有项目名称的xml组合来配置的。

c.IncludeXmlComments(commentsFile);

最后，该指令告诉Swagger要使用哪个文件来获取注释，这就是它在该目录中查找该文件的真正原因。

因此，在这个最后一个指令中指定的内容必须与项目配置的“生成”选项卡中配置的内容相符。

- Chev Paredes

---

这是完美的答案。我经常想避免手动编辑 .csproj，这解释了它的工作原理。 - Shinigamae

非常感谢您指出文档路径的问题。MS docs是针对核心部分的，它假设目录根目录，但对于.NET Framework来说，默认路径是在\bin\目录下，这个答案帮助我弄清楚了这一点。 - undefined

Answer 4

请确保XML Generate配置中的项目属性与您的Swagger配置文件的XML名称匹配。 遵循打印输出以便于理解。 项目属性 Swagger配置文件

- Bruno Jesus Santos

---

哇，谢谢你，修改项目属性以确保生成的输出包含 XML 文档文件是解决我的问题的方法。 - IsolatedThinker

Answer 5

好的，我通过指向根目录来使它起作用。

我仍然不知道为什么它无法检测到 bin 目录中的 xml 文件。 同样的操作是在根目录中添加一个 xml 文件可以解决问题。

代码更改：

var baseDirectory = AppDomain.CurrentDomain.BaseDirectory;
                        //var commentsFileName = Assembly.GetExecutingAssembly().GetName().Name + ".XML";
                        var commentsFileName = "Comments" + ".XML";
                        var commentsFile = Path.Combine(baseDirectory, commentsFileName);

                        c.IncludeXmlComments(commentsFile);

- Tez Wingfield

Answer 6

我从微软文档网站上找到以下解决方案。 在“解决方案资源管理器”中右键单击项目，选择编辑 <project_name>.csproj。 在.csproj文件中手动添加突出显示的行：

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

- Kasun Asela

Answer 7

您可以通过在项目属性下启用选项来获取此文件。只需右键单击项目->属性->生成->输出->选择“生成包含API文档的文件”。请参考下面给出的截图中的选项。此选项适用于所有 .net core 版本。希望这能帮助到某些人。

var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);

- Raghubir Singh

Answer 8

使用 .Net Core 2，我需要以下代码行：

var pathIncludeXmlComments = $@"{env.ContentRootPath}\Events.xml";

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "Events API", Version = "v0.1" });
    c.OperationFilter<AuthorizationHeaderParameterOperationFilter>();
    c.IncludeXmlComments(pathIncludeXmlComments);
});

如果您遇到问题，请在第一行后设置断点，检查“pathIncludeXmlComments”的值，并确认VS2017是否已经将一个.xml文件存储在该位置。

请记住，在项目属性下，“构建”选项卡中，您需要勾选“XML文档文件”框，并将名称设置为与上面文件名相同（例如此处的Events.xml）。

- Mike Gledhill

Answer 9

这个答案是专门针对.NET Framework的，因为大部分文档似乎是针对Core的。我特别在4.6.2上完成了这个任务。

参考Core MS文档。

1. 你想从Nuget获取Swashbuckle。你不需要获取其他任何东西，因为Gen和UI已经嵌入到了Nuget包的框架版本中。对于Core版本，有3个单独的包。
2. 构建解决方案，验证~/App_Start/SwaggerConfig.cs是否已添加到你的解决方案中。根据需要进行自定义。我们稍后会处理XML注释行。

注意：可能可以完全使用项目的“属性”UI来完成下面的步骤，我不知道，但这是我的过程。

卸载Web API启动项目->打开.csproj文件 在的底部，添加两个内容true和$(NoWarn);1591。这将允许生成XML文档资源，并抑制一个警告，因为您没有对成员进行文档化，可能会影响您的项目。 重新加载项目，打开项目属性UI 进入“生成”->对于您所需的配置，您需要勾选“XML文档文件”。这将默认为~\bin\MyProj.xml作为其目录，所以下一步将假设该路径。 返回SwaggerConfig.cs。查找以c.IncludeXmlComments()开头的行。这是您要添加的内容，再次假设您保留了默认生成的XML路径。

string xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "bin", xmlFilename));

保存并在本地运行您的项目，或发布到开发环境，并导航到https://localhost:xxxxx/swagger（本地运行，默认）或您自己设置的自定义路径。

验证解决方案中的Swagger是否正常运行。您不应该看到任何ASP.NET样式的错误页面或类似的内容。

现在进入您的控制器，并开始编写您的文档。我在帖子开头包含的“入门”链接将提供您可以在文档字符串中包含的XML元素类型的示例。这将生成到XML文件中，Swagger使用该文件生成带有您的文档的视图。

我没有尝试对生成的Swagger页面进行任何前端定制，所以我不确定这样做是否会使这个过程变得复杂。这假设您只想要默认的外观。如果有疑问，请一直进行到最后并验证其是否正常工作，然后再考虑添加自定义样式。

- Narish

Answer 10

我希望在这个问题的答案中为大家进一步解释为什么那些代码对Tez无效（对我也无效）。

涉及的代码如下：

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

为了使这个工作起作用，您的swagger文档配置必须写在“startup.cs”或与控制器相同项目中的.cs文件中。

另外，您必须确保正在生成您的XML文件。因此，请右键单击您的项目，进入属性，转到构建，向下滚动到“输出”部分，并选中“XML文档文件”选项。（这些步骤适用于Visual Studio 2019）。

XML文件通常默认命名为“your-project-name”.xml。

$"{Assembly.GetExecutingAssembly().GetName().Name}.xml"

因此，这行代码确保您在swagger配置中的xml文件名为："your-project-name".xml，您的控制器文档位于其中。

在我的情况下，我将swagger配置放在了类库的扩展方法中，所以那行代码生成的xml文件名为："class-library-project-name".xml，而实际上应该是"controller-resident-project-name".xml。

解决方案可以像Tez建议的那样，手动设置XML文件名，因为您已经知道它是什么。

另一种解决方案是在startup.cs中配置swagger，通常与您的控制器位于同一个项目中。

希望这可以帮到您。

- Akin_Glen