NSwag -如何添加评论？

Question

我在一个ASP.Net WebAPI项目中使用NSwag来生成一个swagger接口--它工作得很好。

假设我有一个方法，我想添加一些解释--我该怎么做呢？

我所说的注释是指当API的用户查看文档时将看到的内容。

我用谷歌搜索，大吃大喝，还有...躲避？-但是找不到任何关于它的东西。也许我用错了术语。

Answer 1

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

然后你可以像这样使用注解：

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

Answer 2

您可以使用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方法，您已经添加了适当的文档注释，当您通过API explorer浏览API时，NSwag将获取这些注释并显示它们。如果这样做不起作用，请在.csproj中添加following

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

Answer 3

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