如何使用Swagger尽可能多地描述输入模型

Question

我有一个示例输入模型如下：

public class CarInputModel {
    public string Name { get; set; }
    public string ModelName { get; set; }
}

这个值会来自UI，我可以用swagger用什么样的注解来尽可能描述这个API模型？

Answer 1

您根本不能使用很多注释来描述模型。您主要描述 API 本身

[HttpGet] 和 [HttpPost] 用于 http 属性
[Produces(typeof(CarInputModel)] 用于 return 类型的操作，[ProducesResponseType(typeof(CarInputModel), (int)HttpStatusCode.OK)] 用于基于 http 代码的结果类型（即 return 不同的错误模型）
[Route] 路线本身

此外，您可以使用 Xml 文档来描述类及其参数。

/// <summary>
/// Adds a new car model.
/// </summary>
/// <param name="model">The model to add</param>
/// <response code="201">Returns when the car was added successfully and returns the location to the new resource</response>
/// <response code="400">Invalid Request data.</response>
/// <response code="409">Car mode already exists.</response>
/// <returns>The newly added model on success and a list of errors on failure.</returns>
[HttpPost]
[ProducesResponseType(typeof(CarInputModel), (int)HttpStatusCode.Created)]
[ProducesResponseType(typeof(SerializableError), (int)HttpStatusCode.BadRequest)]
[ProducesResponseType(typeof(void), (int)HttpStatusCode.Conflict)]
public IActionResult AddCar(CarInputModel model) 
{
}

/// <summary>
/// Represents a car
/// </summary>
public class CarInputModel {
    /// <summary>
    /// Name of the car
    /// </summary>
    public string Name { get; set; }
    /// <summary>
    /// Model of the car
    /// </summary>
    public string ModelName { get; set; }
}

为了使用 XmlDocs，您需要在您的项目设置（以及您的模型）中启用 xml 文档的编译，然后将其添加到您的 Startup.cs

services.AddSwaggerGen(options =>
{
    var appEnv = PlatformServices.Default.Application;
    options.IncludeXmlComments(Path.Combine(appEnv.ApplicationBasePath, $"{appEnv.ApplicationName}.xml"));
});

如何使用Swagger尽可能多地描述输入模型

How to describe input model as much as possible using Swagger

c#

swagger

swagger-ui

asp.net-core