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

Question

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>

Solution 1

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:

Solution 2

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:

Solution 3

I am not sure if that's what exactly you're talking about, but you can add comments to the different responses like this

[SwaggerResponse(HttpStatusCode.Unauthorized, "Authorization has been denied for this request")]

This is attribute which you use to decorate your controller method.

Solution 4

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.

View more solutions

Comments

[Helder Sepulveda]

Here is a live example: swashbuckletest.azurewebsites.net/swagger/ui/…

[Helder Sepulveda]

And here is the code behind that: github.com/heldersepu/SwashbuckleTest/blob/…

[Hezye]

Adding response comments can also be done using XML - response code.

[001]

now this is interesting I added /// <summary>The unique identifier</summary> ... just like in the shown example but the description is not displayed in swagger doc, my models are in a separate project (does it matter?)

[Helder Sepulveda]

...strange, but you can see it in my example, Right? _ _ _ It must be something in your swashbuckle configuration, make sure you enable the IncludeXmlComments

[001]

I tried adding <summary> to the models inside the same project. (yes include xml comments is enabled already, I can see comments in the method just fine)

[001]

ASP.NET Core with Swashbuckle - 6.0.0-beta902

[Helder Sepulveda]

Can you create a GitHub project that reproduces your issue? I can help you troubleshoot that way... it could be a bug in that version of Swashbuckle.Core

[001]

Interesting, I created a new web api, and the swagger description works! (the same configuration was used in my original app but description never works! I did a clean /rebuild still doesnt work)

[001]

Its a bug!? if you have external models swagger will not generate the model description. stackoverflow.com/questions/45203601/…

[Helder Sepulveda]

Let us continue this discussion in chat.