ASP.NET Core Web API XML注释配置异常及恢复求助

Let's break this down into two clear parts: first fixing the messy file clutter from your incorrect OutputPath setup, then getting XML documentation working properly for Swagger.

1. Restore Your Project to Normal State #

The root cause of the sudden flood of files is that OutputPath is meant to define a directory for build outputs (like DLLs, PDBs), not a filename. When you set it to ParkyAPI.XML, .NET created a folder with that name and dumped all build artifacts into it. Here's how to fix it:

• First, close Visual Studio 2019 entirely to avoid file locks.
• Open your project's root folder in Finder. You'll see a folder named ParkyAPI.XML — delete this entire folder (it's safe; rebuilding will generate fresh, clean outputs later).
• Edit your .csproj file to revert the OutputPath settings to their defaults. You can either remove the custom Debug/Release PropertyGroup blocks entirely, or correct them to point to directories instead of files. Here's the cleaned-up version:

  <Project Sdk="Microsoft.NET.Sdk.Web">
    <PropertyGroup>
      <TargetFramework>netcoreapp3.1</TargetFramework>
    </PropertyGroup>
    <!-- Optional: Keep custom output paths (set to directories, not files) -->
    <!--
    <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
      <OutputPath>bin/Debug/netcoreapp3.1/</OutputPath>
      <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
    </PropertyGroup>
    <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
      <OutputPath>bin/Release/netcoreapp3.1/</OutputPath>
      <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
    </PropertyGroup>
    -->
    <!-- Rest of your existing ItemGroups go here -->
  </Project>
  

• Save the .csproj file, reopen Visual Studio, and rebuild your project. The solution space will be back to normal, with outputs in the standard bin/Debug/bin/Release directories.

2. Correct XML Documentation Configuration for Swagger #

To generate XML comments and hook them up to Swagger, you need to use dedicated documentation properties (not OutputPath). Here's the step-by-step setup:

Step 1: Update .csproj to Enable XML Generation #

Add these properties to your main <PropertyGroup> (or to Debug/Release-specific blocks if you only want it enabled for certain configurations):

<PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
  <!-- Enable XML documentation file generation -->
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <!-- Set the XML file path (uses project output directory and name automatically) -->
  <DocumentationFile>$(OutputPath)$(AssemblyName).XML</DocumentationFile>
  <!-- Optional: Suppress warning CS1591 (missing XML comments) if you don't want to annotate everything yet -->
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

• GenerateDocumentationFile: Tells .NET to create the XML file containing your code comments.
• DocumentationFile: Ensures the XML file is saved in your build output directory, using your project's name to avoid hardcoding.
• NoWarn: Silences warnings for missing comments (useful if you're just starting out with documentation).

Step 2: Configure Swagger to Read the XML File #

Open your Startup.cs file and update the AddSwaggerGen method to include the XML comments:

using System.Reflection;
using System.IO;
using Microsoft.OpenApi.Models;

public void ConfigureServices(IServiceCollection services)
{
    // ... your existing service configurations ...

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "ParkyAPI", Version = "v1" });

        // Locate the XML file generated during build
        var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.XML";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFilename);
        
        // Inject XML comments into Swagger UI
        c.IncludeXmlComments(xmlPath);
    });
}

Step 3: Add XML Comments to Your Code #

Now you can add meaningful comments to your controllers, actions, and models — these will show up in Swagger:

/// <summary>
/// Retrieves a list of all national parks
/// </summary>
/// <returns>An IEnumerable of NationalParkDto objects</returns>
[HttpGet]
public IActionResult GetAllNationalParks()
{
    // ... your implementation ...
}

Step 4: Test the Setup #

Rebuild your project, run it, and navigate to your Swagger endpoint (usually /swagger). You'll see your XML comments displayed alongside each API endpoint and model definition.

内容的提问来源于stack exchange，提问作者bruzza42