Is is possible to change the contents of the Example Value section generated by NSwag?

Question

We are using NSwag to generate swagger pages for our API. We have a fictitious asp.net core 2.2 controller and the generated swagger pages looks like this:

Is it possible to change the contents of the Example Value (highlighted in yellow)? We would like to display an actual sample value for the testParameter instead of just "string". Is there a data annotation we can use, or some other overriding mechanism available to override this behaviour?

The version of NSwag we are using is NSwag.AspNetCore 13.0.2.

The class that defines the model is:

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

We are using MediatR hence the IRequest.

Here's the controller class:

[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);
        }
    }
}

Thank you kindly, Yves Rochon

Check https://github.com/mattfrear/Swashbuckle.AspNetCore.Filters#request-example — Jota.Toledo, Sep 09 '19 at 21:30

score 4 · Accepted Answer · answered Sep 09 '19 at 19:35

4

On your TestResponse class, add the example tag in xml comments of every property, that will be used in the swagger example. eg

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

answered Sep 09 '19 at 19:35

Gerald Chifanzwa

1,277
7
14

Hi gerryc.inc, the question is how to change the contents of the "Example Value" section of the request (TestQuery object). I added the tag to my TestQuery object as well as the TestParameter property, and the "Example Value" is still showing "string". This doesn't seem to solve my problem, thank you for responding nontheless. – Yves Rochon Sep 09 '19 at 20:01
1

It works, the problem when I first tried was that I wasn't generating the XML Documentation for the assembly that contained the models. Answer accepted, thank you so much! – Yves Rochon Sep 10 '19 at 18:31
gerryc thanks for this solution and Yves thank you for pointing out the xml issue. I had the exact same problem and your posts together made this work. – Stephan Møller Oct 30 '20 at 07:08

Is is possible to change the contents of the Example Value section generated by NSwag?

1 Answers1