c# - 是否可以更改 NSwag 生成的示例值部分的内容？

Question

我们正在使用 NSwag 为我们的 API 生成 swagger 页面。我们有一个虚构的 asp.net core 2.2 Controller ，生成的 swagger 页面如下所示:

是否可以更改示例值的内容(以黄色突出显示)？我们希望显示 testParameter 的实际样本值，而不仅仅是“字符串”。是否有我们可以使用的数据注释，或者其他一些可用于覆盖此行为的覆盖机制？

我们使用的 NSwag 版本是 NSwag.AspNetCore 13.0.2。

定义模型的类是:

public class TestQuery : IRequest<TestResponse>
{
    [DefaultValue("test1")]
    [JsonProperty("testParameter")]
    public string TestParameter { get; set; }
}

我们使用 MediatR，因此使用 IRequest。

这是 Controller 类:

[Authorize, Route("api/route/test")]
[ApiController]
public class TestController : ControllerBase
{
    private readonly IMediator _mediator;

    /// <summary>
    /// TestController constructor
    /// </summary>
    /// <param name="mediator">Dependency Injected mediator reference</param>
    public TestController(IMediator mediator)
    {
        _mediator = mediator;
    }

    /// <summary>
    /// Async method which retrieves a test response for a given testParameter string
    /// </summary>
    /// <remarks>
    ///
    ///        Sample testParameters:   "test1", "test2", "test3"
    ///
    ///        Sample Request:
    ///             {
    ///                 "testParameter": "test1"
    ///             }
    ///
    /// </remarks>
    /// <param name="GetTestResponseQuery">Get test response request model</param>
    /// <returns>A test response</returns>
    [HttpPost]
    public async Task<ApiResponse<TestResponse>> GetTestResponse([FromBody]TestQuery testQuery)
    {
        if (!ModelState.IsValid)
        {
            throw new Exception($"State for model TestQuery is not valid for service {testQuery.TestParameter}");
        }
        else
        {
            var result = await _mediator.Send(testQuery).ConfigureAwait(false);
            return new ApiResponse<TestResponse>(result);
        }
    }
}

谢谢你， 伊夫·罗雄

Answer 1

在您的 TestResponse 类上，在每个属性的 xml 注释中添加 example 标记，该标记将在 swagger 示例中使用。例如

public class TestResponse 
{ 
   /// <summary> 
   /// Property description 
   /// </summary> 
   /// <example>Sample value</example>  
   public string Property { get; set; } 
 }