CODEWITHSUNDEEP
c#swaggerasp.net-core-2.1swashbuckle
alok
alok

Reputation: 1340

C# swagger documentation for individual members of the request body object

We are writing swagger documentation using /// comments in the following way:

/// <summary>
/// Create a new widget
/// </summary>
/// <param name="widget"></param>
[HttpPost("/create")]
[ProducesResponseType(typeof(IPayment), 200)]
[ProducesResponseType(typeof(ErrorResult), 400)]
[ProducesResponseType(typeof(ErrorResult), 404)]
public Task<IActionResult> CreateWidget([FromBody] Widget widget)
{

Now Widget is an implementation of IWidget and the user of the documentation should know in detail what each data member of Widget / IWidget means, what's mandatory, what's optional, and valid values.

We found that the only place to add this description is in 

/// <param name="widget">very big multi line description</param>

While this works for the end user, is there a better way? We ask this because it is much more maintainable if the descriptions are provided inline in the class / interface definition.

Upvotes: 4

Views: 9814

Answers (1)

Helder Sepulveda
Helder Sepulveda

Reputation: 17664

On the same way you document your actions with the /// comments you can also document your models

Here is an example:
http://swagger-net-test.azurewebsites.net/swagger/ui/index?filter=Location#/Location/Location_Get2

The code for that looks like:

/// <summary>
/// ## Geographic coordinates
/// ___
/// A **geographic coordinate system** is a coordinate system used in geography that enables every location on Earth
/// </summary>
public class Location
{
    /// <summary>**Latitude**: a geographic coordinate that specifies the north–south position of a point on the Earth's surface.</summary>
    /// <example>25.85</example>
    [Range(-90, 90)]
    public float Lat { get; set; }

    /// <summary>**Longitude**: a geographic coordinate that specifies the east-west position of a point on the Earth's surface.</summary>
    /// <example>-80.27</example>
    [Range(-180, 180)]
    public float Lon { get; set; }
}

This is how it looks like:

On Post or Put requests the documentation can also be seen on the model tab:

https://swagger-net-test.azurewebsites.net/swagger/ui/index?filter=Company

And as usual under the Models:

Upvotes: 4

Related Questions