How do you add a swagger comment to the “Request a

问题:

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>

回答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:

回答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);
            });

Fore more details

回答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.