C # swagger документация для отдельных членов объекта тела запроса - PullRequest
Новая
       109

C # swagger документация для отдельных членов объекта тела запроса

0 голосов
/ 31 января 2019

Мы пишем swagger документацию, используя /// комментарии следующим образом: 

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

Теперь Widget является реализацией IWidget, и пользователь документации должен подробно знать, что каждый член данных Widget/ IWidget означает, что является обязательным, что является необязательным, и допустимые значения.

Мы обнаружили, что единственное место, где можно добавить это описание, это 

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

Хотя это работает для конечного пользователя, этоесть лучший способ?Мы спрашиваем об этом, потому что это гораздо более легко поддерживать, если описания предоставляются в виде определения класса / интерфейса.

1 Ответ

0 голосов
/ 19 марта 2019

Точно так же, как вы документируете свои действия с помощью комментариев ///, вы также можете документировать свои модели

Вот пример:
http://swagger -net-test.azurewebsites.net / swagger / ui / index? filter = Location # / Location / Location_Get2

Код для этого выглядит следующим образом: 

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