Swagger or OpenApi 3.0 examples in Swashbuckle.AspNetCore

If you’d like to generate request and response examples for your APIs, you no longer need to use my Swashbuckle.AspNetCore.Filters package.

Since May 2018, Swashbuckle.AspNetCore supports adding examples via XML comments.

For installation instructions, see the instructions in Swashbuckle.AspNetCore’s readme.

Request examples – POST

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    [HttpPost]
    public void Submit(WeatherForecast forecast)
    {
        // blah
    }
}

public class WeatherForecast
{
    /// <summary>
    /// The date of the forecast in ISO-whatever format
    /// </summary>
    public DateTime Date { get; set; }

    /// <summary>
    /// Temperature in celcius
    /// </summary>
    /// <example>25</example>
    public int TemperatureC { get; set; }

    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

    /// <summary>
    /// A textual summary
    /// </summary>
    /// <example>Cloudy with a chance of rain</example>
    public string Summary { get; set; }
}

Results in:

Request examples – GET

OpenApi 3.0 supports examples on querystring parameters, which is pretty handy. Just add example= to the param:

/// <summary>
/// Retrieves a specific product by unique id
/// </summary>
/// <param name="id" example="123">The product id</param>
[HttpGet("{id}")]
public Product GetById(int id)

Courtesy of my pull request :-)

Or if you’ve got a reference type in your request (who would do that?), it still works:

// e.g. https://localhost:5001/weatherforecast/AU/MEL/1/2/2020
[HttpGet]
[Route("{country}/{city}/{day}/{month}/{year}")]
public string Get([FromRoute]WeatherRequest wr)
{
    // blah
}

public class WeatherRequest {
    /// <summary>
    /// The 2 digit country code
    /// </summary>
    /// <example>New Zealand, bro</example>
    public string Country { get; set;}
    public string City { get; set; }
    public int Day { get; set; }
    public int Month { get; set; }
    public int Year { get; set; }
}

Response examples

Response examples, again just add XML comments to your response class, and [ProducesResponseType]

[HttpGet]
[ProducesResponseType(typeof(WeatherForecast), StatusCodes.Status200OK)]
public WeatherForecast Get()
{
    // blah
}

// see WeatherForecast at the top of this post

Again, for installation instructions, see the instructions in Swashbuckle.AspNetCore’s readme.

8 thoughts on “Swagger or OpenApi 3.0 examples in Swashbuckle.AspNetCore

  1. So this addition makes it possible to use XML to add one example to a request/response class, right? I have an API where I have many endpoints using the same class, but where I need different examples. Can this way of using XML comments be used to specify the different example values of the request class for the individual endpoint? (From what I read from the Swashbuckle.Examples github, multiple examples for a single request class used to be impossible)

    • If your API accepts the same request for different endpoints, and you want to have different examples for each endpoint, then you’ll need to use my Swashbuckle.AspNetCore.Filters package.

      • (Seems my reply wasn’t submitted successfully, so I will repeat it, apologies if I just can’t see it yet)

        Thanks for your feedback! The project is running is not core, but standard .net framework 4.6 I think. Is there any way I can use those filters anyway?

      • You’re correct with your earlier comment – Swashbuckle.Examples only supports one example for each type on the request. It does support different examples for the same type on the response.

      • Indeed, thanks for the confirmation! I’d like to use your Swashbuckle.AspNetCore.Filters package instead, but I suppose this implies that my project also has to run asp.net core? My project is running framework 4.6, so I’m not sure if they are compatible. I realized this when your installation/use readme referred to files that didn’t exist in my project. Is there a way around this?

      • We’re getting off topic from this blog post, but yes, you’d need to upgrade to ASP.NET Core, which probably isn’t worth it. If however you’re starting a new project, then you should be using .NET Core instead of .NET Framework.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s