您如何在“请求和响应模型”中添加招摇的评论？答案

【问题标题】：How do you add a swagger comment to the "Request and Response Model"?您如何在“请求和响应模型”中添加招摇的评论？
【发布时间】：2017-07-19 10:37:09
【问题描述】：

您可以像下面的示例一样对方法添加注释，但是将 cmets 添加到请求和响应模型呢？

/// <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>

【问题讨论】：

标签： c# asp.net-core swagger swashbuckle

【解决方案1】：

是的，就像 Dimitar 说的，您可以使用 SwaggerResponse 将 cmets 添加到响应中，请求有点不同，就像您将 xml cmets 添加到您应该添加到参数中的操作一样，这里是一个例子：

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; }
    }
}

并且大摇大摆地看起来像：

【讨论】：

这是一个活生生的例子：swashbuckletest.azurewebsites.net/swagger/ui/…
下面是代码：github.com/heldersepu/SwashbuckleTest/blob/…
现在这很有趣，我添加了 ///
唯一标识符
...就像在所示示例中一样，但描述未显示在 swagger 文档中，我的模型在一个单独的项目（重要吗？）
这是一个错误！？如果您有外部模型，swagger 将不会生成模型描述。 stackoverflow.com/questions/45203601/…
让我们continue this discussion in chat。

【解决方案2】：

我使用的是 .net core 3.0，所以除了@Helder 的响应之外，我还必须执行以下两个步骤才能使 XML cmets 可见。

手动编辑项目文件。

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

在startup.cs服务配置方法下面添加。

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

来自microsoft docs for Swagger

XML cmets 可以通过以下方法启用：

手动将突出显示的行添加到 .csproj 文件中：

启用 XML cmets 可为未记录的文件提供调试信息公共类型和成员。指出了未记录的类型和成员通过警告信息。例如，以下消息表示违反警告代码 1591：

【讨论】：

【解决方案3】：

我不确定这是否正是您所说的，但您可以像这样将 cmets 添加到不同的响应中

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

这是你用来装饰你的控制器方法的属性。

【讨论】：

添加响应 cmets 也可以使用 XML - 响应代码来完成。

【解决方案4】：

对于那些对现有答案不满意的人，请确保您的属性类所在的项目也启用了 xml 文档。

就我而言，我的 DTO 有一个单独的项目，并且还需要在其中添加它。请务必使用另一个 IncludeXmlComments 方法包含来自该项目的 xml cmets。

【讨论】：