Swagger无法读取XML文档注释问题排查求助

Let's break down the key issues you're facing and fix them step by step:

1. You're Applying Operation-Level Comments to the Wrong Class #

Your <summary>, <returns>, and <response> comments are attached to the DeleteRequest DTO class, but Swagger expects these operation-specific annotations to live on the controller's action method, not the request model. Swagger reads operation metadata (like summaries and responses) from the action that handles the API call, not the request object itself.

Fix: #

Move those comments to the controller action that processes the delete request. For example:

[HttpDelete("joboffer/delete")]
[ApiKey]
[IsInRole(ApiUserRole.ExternalJobOfferProvider)]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status401Unauthorized)]
[ProducesResponseType(StatusCodes.Status500InternalServerError)]
/// <summary>Deletes a Job Offer</summary>
/// <returns>The ID of the Job Offer in this system</returns>
/// <response code="200">Returns the ID of the deleted Job Offer in this system</response>
/// <response code="401">If the API key is missing, invalid or the key has no access.</response>
/// <response code="500">ArgumentException - If the JobOfferID is an invalid ID.</response>
public IActionResult DeleteJobOffer([FromBody] DeleteRequest request)
{
    // Your deletion logic here
    return Ok(request.JobOfferID);
}

2. Why Your DTO Property Comments Aren't Showing Up #

Even though your XML file includes the JobOfferID property comments, there are a few critical checks to run:

a. Verify XML Generation Settings #

Double-check your project's build configuration:

• Right-click your project → Properties → Build → Under "Output", ensure XML documentation file is checked, and the output path matches exactly what you're using in xmlPath.
• Enable "Treat warnings as errors" temporarily (or set warning level to 4) to catch any missing comment warnings—this can flag issues with XML generation not picking up your comments.

b. Check for Swagger Filter Conflicts #

Your current config uses two custom operation filters:

c.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();
c.OperationFilter<SecurityRequirementsOperationFilter>(false);

Temporarily comment these out and regenerate Swagger. It's possible one of these filters is overriding or clearing comment data. If comments appear after removing them, debug the filter code to find where it's interfering with comment rendering.

c. Validate XML Member Names #

Ensure the member names in your XML file perfectly match your code's namespace and property names. For example, P:MyNamespace.DeleteRequest.JobOfferID must correspond to the full, case-sensitive name of your property (check for typos in namespaces or casing).

d. Clean and Rebuild Your Solution #

Stale build artifacts or outdated XML files often cause this issue. Clean your solution, delete the existing XML file from the output directory, then rebuild to generate a fresh, up-to-date XML file.

3. Additional Swagger Config Check #

• Confirm you're using a version of Swashbuckle.AspNetCore compatible with your ASP.NET Core version (e.g., .NET 6+ requires Swashbuckle.AspNetCore 6.0+).
• For DTO comments, IncludeXmlComments works without extra flags, but if you want to include controller comments too, add the parameter:

  c.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
  

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