How do you add a swagger comment to the "Request and Response Model"?

user_103264 0
Viewed 41641

You can add a comment on the methods like the example below but what about adding comments to the request and response model?

/// <summary>
/// my summary
/// </summary>
/// <remarks>
/// remark goes here.
/// </remarks>
/// <param name="somepara">Required parameter: Example: </param>
/// <return>Returns comment</return>
/// <response code="200">Ok</response>
swagger swashbuckle asp.net-core c#
4 Answers

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:

user_44714690

For those that aren't having luck with the existing answers, make sure that the project your property class lives in has the xml documentation enabled as well.

In my case, I had a separate project for my DTOs and needed to add it in there as well. Be sure to include xml comments from that project as well with another IncludeXmlComments method.

user_126484590
Related