Nswag: How to create an example of request object?

[d1mnewz]

Do we support example values for request objects?

        public async Task<ActionResult<IEnumerable<DummyDto>>> GetConfigurations(
            [FromQuery] DummyQueryDto query) =>
            Ok(await configurationRepository.GetQueryable()
                .ProjectTo<DummyDto>(m_mapper.ConfigurationProvider)
                .ApplyFilter(query.ToFilter())
                .ApplySorting(query.ToSorter())
                .ApplyPagination(query.Offset, query.Count).ToListAsync());
    }

How do I supply example value for this DummyQueryDto object into Swagger UI?

I use OpenApi, SwaggerUi3, AddOpenApiDocument - a really basic setup.

Is there a support for Swashbuckle.AspNetCore.Filters ?

[RicoSuter]

Is there a support for Swashbuckle.AspNetCore.Filters ?

See https://github.com/RicoSuter/NSwag/wiki/Document-Processors-and-Operation-Processors

[d1mnewz]

Should we use the same approach as stated in this article and implement it by ourselves or we can use the stuff which is already available such as Swashbuckle.AspNetCore.Filters?

Can we actually use the same semantics as [SwaggerRequestExample(typeof(DeliveryOptionsSearchModel), typeof(DeliveryOptionsSearchModelExample))] without implementing our own IOperationProcessor?

Currently, I do not see any examples of that kind of stuff. Could you please elaborate?

[RicoSuter]

There is nothing outofthebox yet

See also https://blog.rsuter.com/nswag-tutorial-implement-a-custom-operation-processor-to-define-redoc-code-samples/

[d1mnewz]

Will a PR on this be appreciated?

[RicoSuter]

I think it would make sense to add an attribute to specify this out of the box. However what example object/schema would we use? I think we should only support OpenAPI schemas directly (not ReDoc custom formats).

[mjain123]

Any update on this?

[d1mnewz]

@RicoSuter is it still a thing?

Would the actual impl be any different than just an attribute which would be an OperationProcessor and work with the current operation via C# code?

[davidkeaveny]

I've created a custom IOperationProcessor that can create example responses based on attributes on the controller actions e.g.

[ProducesResponseType(StatusCodes.Status200OK, typeof(Country[]))
[ProducesResponseTypeExample(typeof(CountryExampleGenerator))]
public async Task<IActionResult> GetCountries([FromQuery]Country query, CancellationToken cancellationToken) {
  return await Execute(query, cancellationToken);
}

The first attribute is the ASP.NET Core-provided attribute, which gives the overall shape of the response; the second response is a custom attribute, where the CountryExampleGenerator mentioned exposes an IEnumerable method that returns sample data:

public abstract class ExampleResponseGenerator
{
    private readonly List<object> _examples = new List<object>();

    protected void Register(params object[] exampleData)
    {
        _examples.AddRange(exampleData);
    }

    public IEnumerable Generate()
    {
        foreach (var example in _examples)
        {
            yield return example;
        }
    }
}

public class CountriesExampleProvider : ExampleResponseGenerator
{
    public CountriesExampleProvider()
    {
        Register(new Country
        {
            Name = "Australia",
            CurrencySymbol = 36,
            CurrencyText = "AUD",
            DiallingCode = "61",
            Id = 13,
            IsoCode2 = "AU"
        }, new Country
        {
            Name = "New Zealand",
            CurrencySymbol = 36,
            CurrencyText = "NZD",
            DiallingCode = "64",
            Id = 149,
            IsoCode2 = "NZ"
        }
        );
    }
}

The custom IOperationProcessor then resolves those attributes when generating the OpenApi document (and generates a standard set of responses for e.g. 400 Bad Request, 404 Not Found. However, at the moment, I don't know exactly where to place the final rendered result. On the older Swagger spec, it was on the example property of the response, but with OpenApi, it's in the schema definition (https://swagger.io/docs/specification/2-0/adding-examples/). Any suggestions as to how I can close that particular circle? I'm happy to post the code for my processor if I can get that working.

[davidkeaveny]

Urg, stupid me, I was using services.AddSwaggerDocument() in my Startup and not services.AddOpenApiDocument(). Now I have beautifully rendered examples.