Specify example requests for swagger's "Try it out"

Question

Is there a way to specify example requests for swagger? Maybe even multiple ones?

The Try it out button shows only generic values like:

{
    "firstName": "string",
    "lastName": "string"
}

for

public class User
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

It becomes very difficult to use with large objects when you have to edit all the values first. I know I could use Postman, and I do too, but being able to create multiple good looking and useful examples with swagger would be very nice.

Answer 1

To enable xml comment open .csporj file update propertygroup with these two item:

<PropertyGroup>
  ......
  <GenerateDocumentationFile>True</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Now configure swagger to use generated XML:

builder.Services.AddSwaggerGen(c =>
{
    ........
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

Go to WeatherForecast controller and add comment on Create action like bellow example:

/// <summary>
/// Add new WeatherForecast
/// </summary>
/// <param name="model"></param>
/// <returns>Return success/fail status</returns>
/// <remarks>
/// **Sample request body:**
///
///     {
///        "id": 1,
///        "Date": "2022-06-24",
///        "TemperatureC": 30,
///        "Summary": "TemperatureC is 30 today",
///     }
///
/// </remarks>
/// <response code="200">Success</response>
/// <response code="401">Failed/Unauthorized</response>
[HttpPost]
[ProducesResponseType(typeof(WeatherForecast), 201)]
[ProducesResponseType(400)]
public async Task<ActionResult<WeatherForecast>> Create([FromBody] WeatherForecast model)
{
    WeatherForecast weatherForecast = new WeatherForecast()
    {
        Id = model.Id,
        Date = model.Date,
        TemperatureC =  model.TemperatureC,
        Summary = model.Summary
    };
    return await Task.FromResult(weatherForecast);
}

Sample request body:
{



}

Answer 2

This is how I do it (using .Net Core 7.0, would probably work for older version):

Controller declaration (example):

        [HttpGet("DynValuesCycleGensetPerMicrogridAndDate")]
        public async Task<ActionResult<DynamicValuesByMicrogridDto>> DynValuesCycleGensetPerMicrogridAndDate(
            [SwaggerTryItOutDefaulValue("1")] int microgridId,
            [SwaggerTryItOutDefaulValue("2023-10-07 15:00")] DateTimeOffset dateTimeStart,
            [SwaggerTryItOutDefaulValue("2023-10-09 15:00")] DateTimeOffset dateTimeEnd)
        {
            //...

Program initialisation:

  builder.Services.AddSwaggerGen(options =>
    {
        options.SchemaFilter<SwaggerTryItOutDefaulValue>();
        //...

ISchemaFilter:

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;
using System.Reflection;

namespace GeneralAsp
{
    public class SwaggerTryItOutDefaultValue : ISchemaFilter
    {
        /// <summary>
        /// Apply is called for each parameter
        /// </summary>
        /// <param name="schema"></param>
        /// <param name="context"></param>
        public void Apply(OpenApiSchema schema, SchemaFilterContext context)
        {
            if (context.ParameterInfo != null)
            {
                var att = context.ParameterInfo.GetCustomAttribute<SwaggerTryItOutDefaultValueAttribute>();
                if (att != null)
                {
                    schema.Example = new Microsoft.OpenApi.Any.OpenApiString(att.Value.ToString());
                }
            }
        }
    }
}

Attribute:

namespace GeneralAsp
{
    public class SwaggerTryItOutDefaultValueAttribute : Attribute
    {
        public string Value { get; }

        public SwaggerTryItOutDefaultValueAttribute(string value)
        {
            Value = value;
        }
    }
}

Answer 3

In .Net5 you can add a SchemaFilter to Swagger in the Startup.cs

public override void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SchemaFilter<ExampleSchemaFilter>();
    });
}

In the ExampleSchemaFilter.cs you simply define an OpenApiObject for your specific class:

using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerGen;

public class ExampleSchemaFilter : ISchemaFilter
{
    public void Apply(OpenApiSchema schema, SchemaFilterContext context)
    {
        if (context.Type == typeof(User))
        {
            schema.Example = new OpenApiObject()
            {
                ["firstName"] = new OpenApiString("John"),
                ["lastName"] = new OpenApiString("Doe"),
            };
        }
    }
}

Answer 4

With ASP.NET Core 3.1, Swagger OAS 3 and Swashbuckle.AspNetCore 5.4.1, the following model class + XML comments works for me:-

    /// <summary>
    /// A user.
    /// </summary>
    public class User
    {
        /// <summary>
        /// The user's first name.
        /// </summary>
        /// <example>Jane</example>
        public string FirstName { get; set; }

        /// <summary>
        /// The user's last name.
        /// </summary>
        /// <example>Austin</example>
        public string LastName { get; set; }
    }

Now when I click "Try it Out" (for a POST operation that takes a User model in the message body), I get the defaults:-

{
    "firstName": "Jane",
    "lastName": "Austin"
}