如何在 C# 中为 Swagger 中的一个请求对象定义多个请求示例?

Question

对于请求，在 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中为一个请求对象(DeliveryOptionsSearchModel(定义多个请求示例？

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

还有其他方法可以解决这个问题吗？

我正在使用以下软件包

Answer 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": "[phone]",
///         "email": "[e-mail]"
///     }
///
/// Second Schema:
///
///     GET /Todo
///     {
///         "name": "Name",
///         "surname": "Surname",
///         "personalCode": "12345",
///         "dateOfBirth": "2020-03-30T00:00:00",
///         "phoneNumber": "[phone]",
///         "email": "[e-mail]"
///     }
///
/// </remarks>

你会得到这个结果：

两个申请架构的图像

Answer 2

<a href="https://c2n.me/46JxgoT"><img src="https://c2n.me/46JxgoT.png" alt="Swagger UI - Google Chrome"/></a>

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

我这样解决了这个问题，看看///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": "[phone]",
///         "email": "[e-mail]"
///     }
///
///     POST /Todo
///     {
///         "name": "Name",
///         "surname": "Surname",
///         "personalCode": "12345",
///         "dateOfBirth": "2020-03-30T00:00:00",
///         "phoneNumber": "[phone]",
///         "email": "[e-mail]"
///     }
///
/// </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
}