NSwag-如何添加评论？

问题描述

我在ASP.Net WebAPI项目中使用NSwag生成一个灵活的界面-效果很好。

说我有一种方法要向其中添加一些解释-我该怎么做？

通过评论，我的意思是当API用户查看文档时会看到的东西。

我已经用谷歌搜索，加油并...躲开了？ -但找不到任何相关信息。也许我用错了字眼。

解决方法

您可以使用Document comments实现目标。例如

/// <summary>This method changes the point's location by
///    the given x- and y-offsets.
/// <example>For example:
/// <code>
///    Point p = new Point(3,5);
///    p.Translate(-1,3);
/// </code>
/// results in <c>p</c>'s having the value (2,8).
/// </example>
/// </summary>

public void Translate(int xor,int yor) {
    X += xor;
    Y += yor;
}

Translate是您的API方法，并且您添加了适当的文档注释NSwag会在您通过API资源管理器探索API时将其选中并显示出来。如果这样不起作用，请在您的.csproj中添加following

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

对于在另一个答案中发布的XML方法，也可以使用Swashbuckle.AspNetCore.Annotations包，如果您更喜欢基于属性的方法。

要在 NSwag 中使用基于注释的文档，您必须安装包 NSwag.Annotations。

然后你可以使用这样的注释：

[SwaggerResponse(HttpStatusCode.OK,typeof(MyResponseType),Description = "Returns the object containing data ...")]

asp.net-core openapi swagger swagger