XML Documentation not picked up in Swagger

Viewed 291

I'm setting up a public facing API and I've added Xml comments to the objects to add some extra info. Example of one of my request object:

/// <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> 
[ApiKey]
[IsInRole(ApiUserRole.ExternalJobOfferProvider)]
[DeleteRequest("joboffer/delete")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status401Unauthorized)]
[ProducesResponseType(StatusCodes.Status500InternalServerError)]
public class DeleteRequest : WebProxyRequest<MyResponse>
{
    /// <summary>
    /// <para>The ID to look up the to be deleted Job Offer in the system.</para>
    /// <para>Type: guid</para>
    /// <para>Reguired</para>
    /// </summary>
    [Required]
    public Guid JobOfferID { get; set; }
}

I've configured swagger as described to use Xml comments:

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyAPI", Version = "v1" });
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
    c.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();
    c.OperationFilter<SecurityRequirementsOperationFilter>(false);
    c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
    {
        Description = "Standard Authorization header using the API Key scheme.",
        In = ParameterLocation.Header,
        Name = Constants.ApiKeyName,
        Type = SecuritySchemeType.ApiKey
    });
});

I've double checked that the xmlPath variable does contain the correct file path for the assembly's XML file, which does contain the following segment for this class:

    <?xml version="1.0"?>
    <doc>
        <assembly>
            <name>MyAPI</name>
        </assembly>
        <members>
            <member name="T:MyNamespace.DeleteRequest">
                <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> 
            </member>
            <member name="P:MyNamespace.DeleteRequest.JobOfferID">
                <summary>
                <para>The ID to look up the to be deleted Job Offer in the system.</para>
                <para>Type: guid</para>
                <para>Reguired</para>
                </summary>
            </member>

But alas, no mentioning of the comments in the generated swagger.json and as a result nothing in the UI page.:

...
  "components": {
    "schemas": {
...
      "DeleteRequest": {
        "type": "object",
        "properties": {
          "jobOfferID": {
            "type": "string",
            "format": "uuid"
          }
        },
        "additionalProperties": false
      },
...

What am I'm overlooking? I've spend hours trying to get the comments to show.

0 Answers
Related