如何在 C# 中用 swagger 为一个请求对象定义多个请求示例？答案

【问题标题】：how to define multiple request example for one Request Object in swagger in C#?如何在 C# 中用 swagger 为一个请求对象定义多个请求示例？
【发布时间】：2019-12-11 07:42:54
【问题描述】：

对于请求，在 Swagger 2.0 规范中，跨所有 API 端点定义的每个请求对象只有一个模式。因此，如果我要在多个 API 端点中提供相同的请求对象，即在多个控制器操作上，如下所示：

DeliveryOptions.cs
[SwaggerRequestExample(typeof(DeliveryOptionsSearchModel), typeof(DeliveryOptionsSearchModelExample1))]
public async Task<IHttpActionResult> DeliveryOptionsForAddress(DeliveryOptionsSearchModel search)
...    

// maybe in some other controller, e.g. Search.cs
[SwaggerRequestExample(typeof(DeliveryOptionsSearchModel), typeof(DeliveryOptionsSearchModelExample2))]        
public async Task<IHttpActionResult> Search(DeliveryOptionsSearchModel search)


// for Example 
public class DeliveryOptionsSearchModel
{
  public string name {get; set;}
}

public class DeliveryOptionsSearchModelExample1 : Swashbuckle.Examples.IExamplesProvider 
{
    public object GetExamples()
    {
        return new DeliveryOptionsSearchModel
        {
            name= "abc"
        };
    }
}

public class DeliveryOptionsSearchModelExample2 : Swashbuckle.Examples.IExamplesProvider 
{
    public object GetExamples()
    {
        return new DeliveryOptionsSearchModel
        {
            name= "xyz"
        };
    }
}

DeliveryOptionsSearchModel 对象在整个 Swagger 文档中只定义一次。

如何在 C# asp .net 的 swagger 中为一个请求对象(DeliveryOptionsSearchModel) 定义多个请求示例？

问题在于它没有为DeliveryOptionsSearchModel 对象渲染两个不同的示例。 Swagger UI 仅显示所有 API 端点的一个示例类（例如 - DeliveryOptionsSearchModelExample2）。

还有其他办法解决吗？

I am using the following packages

【问题讨论】：

标签： c# swagger-ui swagger-2.0 swashbuckle

【解决方案1】：

您可以为每个请求定义多个方案，如下所示：

    ///<remarks>
    /// First Schema:
    ///
    ///     GET /Todo
    ///     {
    ///         "flatId": "62a05ac8-f131-44c1-8e48-f23744289e55",
    ///         "name": "Name",
    ///         "surname": "Surname",
    ///         "personalCode": "12345",
    ///         "dateOfBirth": "2020-03-30T00:00:00",
    ///         "phoneNumber": "+37122345678",
    ///         "email": "email@mail.com"
    ///     }
    ///
    /// Second Schema:
    ///
    ///     GET /Todo
    ///     {
    ///         "name": "Name",
    ///         "surname": "Surname",
    ///         "personalCode": "12345",
    ///         "dateOfBirth": "2020-03-30T00:00:00",
    ///         "phoneNumber": "+37122345678",
    ///         "email": "email@mail.com"
    ///     }
    ///
    /// </remarks>

你得到这个结果：

Image of two schemas for requisition

【讨论】：

【解决方案2】：

&lt;a href="https://c2n.me/46JxgoT"&gt;&lt;img src="https://c2n.me/46JxgoT.png" alt="Swagger UI - Google Chrome"/&gt;&lt;/a&gt;

我有同样的问题，我是这样排序的。我试图通过CreateSomethinkExample : IExampleProvider<CreateSomethink> 做到这一点但似乎 Swagger 核心不支持多个请求示例。

我是这样整理这个问题的，看///Doc

 /// <summary>
    /// Resident creation endpoint. Creating new Resident in DB and returns created item
    /// </summary>
    /// <response code="201">Success-full creation returns created item</response>
    /// <response code="400">Failed creation returns status and list of errors</response>
    /// <response code="404">House or Flat not found</response>
    /// <response code="500">Server error</response>
    /// /// <remarks>
    /// Sample request:
    ///
    ///     POST /Todo
    ///     {
    ///         "flatId": "62a05ac8-f131-44c1-8e48-f23744289e55",
    ///         "name": "Name",
    ///         "surname": "Surname",
    ///         "personalCode": "12345",
    ///         "dateOfBirth": "2020-03-30T00:00:00",
    ///         "phoneNumber": "+37122345678",
    ///         "email": "email@mail.com"
    ///     }
    ///
    ///     POST /Todo
    ///     {
    ///         "name": "Name",
    ///         "surname": "Surname",
    ///         "personalCode": "12345",
    ///         "dateOfBirth": "2020-03-30T00:00:00",
    ///         "phoneNumber": "+37122345678",
    ///         "email": "email@mail.com"
    ///     }
    ///
    /// </remarks>
    [AllowAnonymous]
    [ProducesResponseType(typeof(SuccessResidentCreationResponse), 201)]
    [ProducesResponseType(typeof(FailedResidentCreationResponse), 400)]
    [HttpPost(ApiRoutes.ResidentRoute.ResidentV1)]
    public async Task<IActionResult> CreateFlat([FromServices] Iconfiguration configuration, [FromBody] CreateResidentRequest request)
    {
        //Some logic
    }

【讨论】：