This library contains a bunch of extensions for Swashbuckle.AspNetCore.
To use the extensions, install NuGet package into your project.
Then use whichever annotations or extensions (filters) you need.
Annotate your controller action methods with the OperationErrorCodes
attribute to indicate which error codes can be expected to be returned:
using Microsoft.AspNetCore.Mvc;
[HttpGet("{id}")]
[OperationErrorCodes("user_not_found", "user_ineligible_for_account")]
public async Task<IActionResult> CreateAccountAsync([FromRoute, Required] string id){ }
Then configure Swashbuckle to incorporate the error codes into the generated swagger documentation. In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
services.AddSwaggerGen(options =>
{
options.AddErrorCodes();
})
You can optionally add descriptions to the error codes by supplying an instance of IDictionary<string, string>
to AddErrorCodes(...)
.
You can use tags to provide additional metadata to operations. You can do this by annotating your controllers or action methods with the OperationExtraTag
attribute:
using Microsoft.AspNetCore.Mvc;
[Route("/devices")]
[OperationExtraTag("Devices", Description = "Accessing Device Operations", ExternalDocsUrl = "https://redocly.github.io/redoc/example-logo.png")]
public class DevicesController : ControllerBase { }
Then configure Swashbuckle to incorporate the extra tags into the generated swagger documentation. In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
services.AddSwaggerGen(options =>
{
options.AddExtraTags();
})
You can further control the tags by grouping them.
Use x-tagGroups
to group tags in the Reference docs navigation sidebar.
Add controllers you wish to group:
using Microsoft.AspNetCore.Mvc;
[Route("/devices")]
public class DevicesController : ControllerBase { }
[Route("/telemetry")]
public class TelemetryController : ControllerBase { }
Then configure Swashbuckle to incorporate the tag groups into the generated swagger documentation. In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
using Tingle.AspNetCore.Swagger;
var tagGroups = new new List<OpenApiTagGroup>
{
new OpenApiTagGroup("Engineering", new List<string>
{
"Telemetry",
"Devices"
})
};
services.AddSwaggerGen(options =>
{
options.AddTagGroups(tagGroups);
})
By default, any tags that haven't been added to any group will be left as is. However, if you'd like to add them to a ungrouped
grouping you can set the addUngrouped
parameter in AddTagGroups(...)
to true
.
In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
services.AddSwaggerGen(options =>
{
options.AlwaysShowBadRequestResponse();
})
In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
services.AddSwaggerGen(options =>
{
options.AlwaysShowAuthorizationFailedResponse();
})
Sometimes you may want to hide your endpoints internal use only. You can do this by annotating your controllers or action methods with the InternalOnly
attribute:
using Microsoft.AspNetCore.Mvc;
[InternalOnly]
[Route("/devices")]
public class DevicesController : ControllerBase { }
Then you can add the x-internal
to the API description. In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
services.AddSwaggerGen(options =>
{
options.AddInternalOnlyExtensions();
})
Then you can generate an external and internal version of the API. More details can be found here.
You can add the X-Correlation-ID
headers to all operations, that are used to uniquely identify the HTTP request, as shown below:
In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
services.AddSwaggerGen(options =>
{
options.AddCorrelationIds();
})
By default, the header is only indicated to be part of the response headers. If you'd like the header to appear among the request headers you can set the includeInRequests
parameter in AddCorrelationIds(...)
to true
.
Use x-logo
to add a custom logo image to your API reference documentation. For example:
In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
var logo = new OpenApiReDocLogo
{
Url = "https://redocly.github.io/redoc/example-logo.png",
BackgroundColor = "#FFFFFF",
AltText = "Example logo"
};
services.AddSwaggerGen(options =>
{
options.AddReDocLogo();
})
When specified, the logo image is displayed above the navigation sidebar, on the left side of the API documentation page.
You can automatically discover API versions declared in code and generate swagger documents as shown below:
In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
services.AddSwaggerGen(options =>{});
services.AddSwaggerDocsAutoDiscovery(title: "My docs", description: "My description", skipDeprecated: false, deprecationSuffix: "[deprecated]");
If you'd like to add swagger docs for only particular API versions.
Annotate a controller with an API version:
using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;
[ApiVersion("v1")]
[Route("/devices")]
public class DevicesController : ControllerBase { }
In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
services.AddSwaggerGen(options =>
{
options.AddDocument(documentName: "v1", versionName: "v1", title: "My v1 docs", description: "My v1 docs");
});
You can use the various AddDocument(...)
or AddDocuments(...)
overloads to also achieve the same result.
In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
services.AddSwaggerGen(options => { });
services.AddSwaggerXmlToMarkdown();
In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
services.AddSwaggerGen(options => { });
services.AddSwaggerEnumDescriptions();
This should be called after all XML documents have been added.
In the Program.cs
or Startup.cs
:
using Microsoft.Extensions.DependencyInjection;
services.AddSwaggerGen(options =>
{
options.IncludeXmlCommentsFromInheritDocs();
});
You can alternatively use the IncludeXmlComments(...)
extension to add XML comments from a file in a certain directory or from the assembly of the specified type.