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.