3

I use NSwag in an ASP.Net WebAPI project to generate a swagger interface - which works great.

Say I have a method I want to add some explanations to - how can I do that?

By comment I mean something that when a user of the API is looking at the documentation will see.

I have googled, binged and ... ducked? - but was unable to find anything about it. Maybe I am using wrong terms.

Kjensen
  • 12,447
  • 36
  • 109
  • 171
  • refer to [this](https://stackoverflow.com/questions/45188033/how-do-you-add-a-swagger-comment-to-the-request-and-response-model/45192302) – Yiyi You Oct 07 '20 at 04:09

3 Answers3

3

You can use Document comments to achieve your goal. For example

/// <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 is your API method and you've added proper documentation comments NSwag will pick those up and show them when you explore the API via the API explorer. If that doesn't work add the following in your .csproj

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
Muhammad Hannan
  • 2,389
  • 19
  • 28
3

To use annotation-based documentation with NSwag you must install the package NSwag.Annotations.

Then you can use annotations like that:

[SwaggerResponse(HttpStatusCode.OK, typeof(MyResponseType), Description = "Returns the object containing data ...")]
alsami
  • 8,996
  • 3
  • 25
  • 36
1

Alternatively to the XML approach posted in another answer you can use the Swashbuckle.AspNetCore.Annotations package as well if you prefer an attribute-based approach.

Ben Sampica
  • 2,912
  • 1
  • 20
  • 25