找不到 XML 注釋文件 - Swagger

Question

這當然是讓您發瘋的原因之一。 正如標題所示，我只是想顯示使用 swagger 從 xml 文件中提取的注釋。

我似乎已經根據 swagger 文檔采取了所有步驟，但無濟於事。 希望你們善良的人能指出我正確的方向。

采取的步驟：

確保文件存在：

配置的SwaggerConfig.cs

我也嘗試過更改路徑：@"bin/....xml"

似乎沒有任何效果。

**錯誤“找不到文件”：**

任何人都可以指出我正確的方向嗎？

問候，

Answer 1

這些是我在 .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>

Answer 2

在 .net 核心 3.0 中

<GenerateDocumentationFile>true</GenerateDocumentationFile>

在 .csproj 文件的 PropertyGroup 標簽中

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 使用哪個文件來獲取注釋，這是它在該目錄中查找該文件的真正原因。

因此，最后一條指令中指示的內容必須根據項目配置的 Build 選項卡中的配置。

Answer 4

好的，所以我設法通過指向根目錄使其工作。

我仍然不知道為什么它無法檢測到 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);

Answer 5

確保 XML Generate 配置中的項目屬性與 swagger 配置文件的 XML 名稱匹配。 遵循印刷品以促進理解

項目屬性

招搖配置

Answer 6

使用 .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 ）。

Answer 7

我只是想回答這個問題，以進一步解釋為什么這些代碼對 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-項目名稱”.xml。

正如 Tez 建議的那樣，解決方案是手動設置 XML 文件名，因為您已經知道它是什么。

另一種解決方案是在 startup.cs 中配置 swagger，它通常與您的控制器在同一個項目中。

希望這會有所幫助。

Answer 8

可能是我有點晚了，但想分享我的修復程序，我在 Notepad++ 中打開了 .csproj 文件並刪除了所有注釋 ()，保存了文件並再次打開了解決方案，a（如果您的解決方案有多個項目，處理所有 .csproj 文件）

Answer 9

我從 Microsoft Document 站點找到了以下解決方案。 在解決方案資源管理器中右鍵單擊該項目並選擇編輯 <project_name>.csproj。 手動將突出顯示的行添加到 .csproj 文件：

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