How do you add a swagger comment to the "Request and Response Model"?
I'm using .net core 3.0, so in addition to @Helder's response, I had to do below two more steps to make XML comments visible.
manually edit the project file.
<PropertyGroup>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
add below to startup.cs service configuration method.
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "My Good API",
Version = "v1",
Description = "Doesn't hurt to add some description."
});
// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
From the microsoft docs for Swagger
XML comments can be enabled with the following approaches:
- Manually add the highlighted lines to the .csproj file:
Enabling XML comments provides debug information for undocumented public types and members. Undocumented types and members are indicated by the warning message. For example, the following message indicates a violation of warning code 1591:
Yes just like Dimitar said, you can add comments to the responses with SwaggerResponse, the request is a bit different, just like you added xml comments to your action you should add to the parameters, here is an example:
using Swagger.Net.Annotations;
using System;
using System.Collections.Generic;
using System.Net;
using System.Web.Http;
using System.Web.Http.Results;
namespace Swagger_Test.Controllers
{
public class IHttpActionResultController : ApiController
{
[SwaggerResponse(HttpStatusCode.OK, "List of customers", typeof(IEnumerable<int>))]
[SwaggerResponse(HttpStatusCode.NotFound, Type = typeof(NotFoundResult))]
public IHttpActionResult Post(MyData data)
{
throw new NotImplementedException();
}
}
/// <summary>My super duper data</summary>
public class MyData
{
/// <summary>The unique identifier</summary>
public int id { get; set; }
/// <summary>Everyone needs a name</summary>
public string name { get; set; }
}
}
And in swagger that will look like: