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.

Add Swagger request and response examples in XML

A few years ago I blogged about how to add Swagger examples for requests and responses. But those examples are rendered in JSON. What if your application supports XML, wouldn’t it be nice to see the examples in XML too? Let me show you how to set that up (in .NET Core).

Enable XML requests and responses

Firstly, you need to enable XML in your requests and responses.

services
.AddMvc(options => {
    options.InputFormatters.Add(new XmlSerializerInputFormatter());
    options.OutputFormatters.Add(new XmlSerializerOutputFormatter());
})

Swashbuckle will now show XML in the supported content types select list for the request:

and for the response:

Now you’ll need to consume version 5.0.0-beta or later of my Swashbuckle.AspNetCore.Filters NuGet package. Follow the instructions and implement IExamplesProvider<T>. Then when you choose application/xml in the request or response select list, you’ll see the example in XML format:

Or in JSON format (as before):

Add an authorization header to your swagger-ui with Swashbuckle (revisited)

Just over a year ago I blogged a simple way to add an authorization header to your swagger-ui with Swashbuckle. Although that works, Swagger-UI and Swashbuckle support a better way, which I’ll describe below.

Before starting I assume you’ve already got OAuth2 setup correctly on your application (using bearer tokens), and you have decorated your controllers and actions with [Authorize] attributes. If you haven’t, that is beyond the scope of this blog post. Here all I’m doing is explaining how to configure Swashbuckle.

First, you need to tell Swashbuckle what security your API has:

services.AddSwaggerGen(options =>
{
    options.AddSecurityDefinition("oauth2", new ApiKeyScheme
    {
        Description = "Standard Authorization header using the Bearer scheme. Example: \"bearer {token}\"",
        In = "header",
        Name = "Authorization",
        Type = "apiKey"
    });

This adds a securityDefinition to the bottom of the Swagger document, which Swagger-UI renders as an “Authorize” button:

Clicking that brings up a dialog box where you can put your bearer token:

The next thing we need to do is tell Swashbuckle which of our actions require Authorization. To do that you can use the SecurityRequirementsOperationFilter:

services.AddSwaggerGen(options =>
{
    options.AddSecurityDefinition("oauth2", new ApiKeyScheme
    {
        Description = "Standard Authorization header using the Bearer scheme. Example: \"bearer {token}\"",
        In = "header",
        Name = "Authorization",
        Type = "apiKey"
    });

    options.OperationFilter<SecurityRequirementsOperationFilter>();

You can either download the SecurityRequirementsOperationFilter from here, or, if you’re using ASP.NET Core you can install my Swashbuckle.AspNetCore.Filters package from NuGet, which includes it (and other filters).

The SecurityRequirementsOperationFilter adds a security property to each operation in the Swagger document, which renders in Swagger-UI as a padlock next to the operation:

Once you’ve done that, when you “Try it out” using the Swagger-UI, the authorization header with your bearer token should be sent to your API.

Show Swagger documentation on Azure Service Fabric

Another blog post in what seems to be becoming a series of posts on Swagger.

Swashbuckle allows you to include XML comments on your API’s Swagger page. To do this you need to set your Build to output an XML file, which Swashbuckle reads the XML comments from.
Don’t forget to add that XML file to the “Release” build configuration too, otherwise you won’t have XML comments when your application is actually deployed to an environment.

Here’s a handy code snippet for your .NET Core .csproj file:

  <!-- Begin Swagger documentation file-->
  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\Debug\net46\win10-x64\swagger.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
    <DocumentationFile>bin\Debug\net46\win10-x64\swagger.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
    <DocumentationFile>bin\Release\net46\win10-x64\swagger.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
    <DocumentationFile>bin\Release\net46\win10-x64\swagger.xml</DocumentationFile>
    <NoWarn>1701;1702;1705;1591</NoWarn>
  </PropertyGroup>
  <!-- End Swagger documentation file-->

Additionally, if your application is deployed on Azure Service Fabric, you will also need to copy the XML file to your PublishDir, with the following snippet in your .csproj:

  <Target Name="PrepublishScript" BeforeTargets="PrepareForPublish">
    <ItemGroup>
      <DocFile Include="bin\x64\$(Configuration)\$(TargetFramework)\win10-x64\*.xml" />
    </ItemGroup>
    <Copy SourceFiles="@(DocFile)" DestinationFolder="$(PublishDir)" SkipUnchangedFiles="false" />
  </Target>

And of course you need to tell Swashbuckle to use that XML file via the .IncludeXmlComments() method mentioned above.

Add an upload button to your swagger page

The swagger adventures continue…

In .NET Core the current recommended way to upload a file in ASP.NET is with an IFormFile.

If you’re using an IFormFile in your ASP.NET Web Api like so:

[HttpPost("upload")]
public IActionResult UploadFile(IFormFile file)
{

N.B. Update December 2018. As of Swashbuckle 4.0, IFormFile is supported out of the box, so the filter below is no longer needed.

If you do this, the Swagger page as rendered by Swashbuckle won’t look correct:

However, if you install version 2.5.0 or later of my Swashbuckle.AspNetCore.Examples NuGet package, then you can add the [AddSwaggerFileUploadButton] attribute to your controller action, like so:

[HttpPost("upload")]
[AddSwaggerFileUploadButton]
public IActionResult UploadFile(IFormFile file)
{

and then enable my filter in your Startup.cs:

services.AddSwaggerGen(c =>
{
    c.OperationFilter<AddFileParamTypesOperationFilter>();

Then you’ll get a nice upload button:

N.B. Update December 2018. As of Swashbuckle 4.0, IFormFile is supported out of the box, so the filter above is no longer needed.

Add an authorization header to your swagger-ui with Swashbuckle

Edit July 2018: I’ve blogged a better way to do this. Add an authorization header to your swagger-ui with Swashbuckle (revisited).

Out of the box there’s no way to add an Authorization header to your API requests from swagger-ui. Fortunately (if you’re using ASP.NET), Swashbuckle 5.0 is extendable, so it’s very easy to add a new IOperationFilter to do it for us:

public class AddAuthorizationHeaderParameterOperationFilter : IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        if (operation.parameters != null)
        {
            operation.parameters.Add(new Parameter
            {
                name = "Authorization",
                @in = "header",
                description = "access token",
                required = false,
                type = "string"
            });
        }
    }
}

Now all you need to do is register it in your EnableSwagger call:

configuration
    .EnableSwagger(c =>
    {
        c.SingleApiVersion("v1", "Commerce Services - Discounts");

        foreach (var commentFile in xmlCommentFiles)
        {
            c.IncludeXmlComments(commentFile);
        }

        c.OperationFilter<ExamplesOperationFilter>();
        c.OperationFilter<AddAuthorizationHeaderParameterOperationFilter>();
    })
    .EnableSwaggerUi(config => config.DocExpansion(DocExpansion.List));

Once that’s done it’ll give you an input field where you can paste your Authorization header. Don’t forget to add the word “bearer” if you’re using a JWT token:

Edit July 2018: I’ve blogged a better way to do this. Add an authorization header to your swagger-ui with Swashbuckle (revisited).