| 📣 This is fork of awesome Swashbuckle.AspNetCore! |
|---|
| * DotSwashbuckle supports only .NET 8 and newer versions |
| * All credits for this project goes to domaindrivendev and Swashbuckle.AspNetCore |
| * All credits for DotSwashbuckle.AspNetCore.Filters goes to mattfrear |
Swagger tooling for APIs built with .NET 8. Generate beautiful API documentation, including a UI to explore and test operations, directly from your routes, controllers and models.
In addition to its Swagger 2.0 and OpenAPI 3.0 generator, DotSwashbuckle also provides an embedded version of the awesome swagger-ui that's powered by the generated Swagger JSON. This means you can complement your API with living documentation that's always in sync with the latest code. Best of all, it requires minimal coding and maintenance, allowing you to focus on building an awesome API.
And that's not all ...
Once you have an API that can describe itself in Swagger, you've opened the treasure chest of Swagger-based tools including a client generator that can be targeted to a wide range of popular platforms. See swagger-codegen for more details.
DotSwashbuckle is only compatible with .NET 8 or newer version
Change the csproj nuget reference
-<PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
+<PackageReference Include="DotSwashbuckle.AspNetCore" Version="3.0.11" />Uninstall the swashbuckle CLI tool
dotnet tool uninstall --global Swashbuckle.AspNetCore.Cli
Install DotSwashbuckle CLI tool
dotnet tool install --global --version 3.0.11 DotSwashbuckle.AspNetCore.Cli
BenchmarkDotNet v0.13.12, Windows 11 (10.0.22631.3085/23H2/2023Update/SunValley3) AMD Ryzen 9 5950X, 1 CPU, 32 logical and 16 physical cores .NET SDK 8.0.200-preview.23624.5 [Host] : .NET 8.0.0 (8.0.23.53103), X64 RyuJIT AVX2 Job-YEPNHV : .NET 8.0.0 (8.0.23.53103), X64 RyuJIT AVX2
WarmupCount=2
| Method | Mean | Error | StdDev | Gen0 | Gen1 | Allocated |
|---|---|---|---|---|---|---|
| DotSwashbuckleOpenApi | 503.9 ms | 3.93 ms | 3.28 ms | 9000.0000 | 3000.0000 | 162.55 MB |
-
Install the standard Nuget package into your ASP.NET Core application.
Package Manager : Install-Package DotSwashbuckle.AspNetCore -Version 3.0.11 CLI : dotnet add package --version 3.0.11 DotSwashbuckle.AspNetCore -
In the
ConfigureServicesmethod ofStartup.cs, register the Swagger generator, defining one or more Swagger documents.using Microsoft.OpenApi.Models;
services.AddMvc(); services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" }); });
-
Ensure your API actions and parameters are decorated with explicit "Http" and "From" bindings.
[HttpPost] public void CreateProduct([FromBody]Product product) ...
[HttpGet] public IEnumerable<Product> SearchProducts([FromQuery]string keywords) ...
NOTE: If you omit the explicit parameter bindings, the generator will describe them as "query" params by default.
-
In the
Configuremethod,you should expose the generated Swagger as JSON endpoint(s) by one of following method:- Add endpoints if you're using endpoint-based routing.
app.MapEndpoints(endpoints => { // ... endpoints.MapSwagger(); });
- Insert middleware
app.UseSwagger();
At this point, you can spin up your application and view the generated Swagger JSON at "/swagger/v1/swagger.json."
-
Optionally, insert the swagger-ui middleware if you want to expose interactive documentation, specifying the Swagger JSON endpoint(s) to power it from.
app.UseSwaggerUI(c => { c.SwaggerEndpoint("v1/swagger.json", "My API V1"); });
Now you can restart your application and check out the auto-generated, interactive docs at "/swagger".
Iif you want to continue using Newtonsoft Serializer, you need to install a separate package and explicitly opt-in. Out-of-the-box DotSwashbuckle will assume you're using the STJ serializer and generate Schema's based on its behavior. If you're using Newtonsoft, then you'll need to install a separate DotSwashbuckle package and explicitly opt-in. This is a required step, regardless of which version of ASP.NET Core you're using.
In summary ...
If you're using System.Text.Json (STJ), then the setup described above will be sufficient, and STJ options/attributes will be automatically honored by the Swagger generator.
If you're using Newtonsoft, then you'll need to install a separate package and explicitly opt-in to ensure that Newtonsoft settings/attributes are automatically honored by the Swagger generator:
Package Manager : Install-Package DotSwashbuckle.AspNetCore.Newtonsoft -Version 3.0.11
CLI : dotnet add package --version 3.0.11 DotSwashbuckle.AspNetCore.Newtonsoft
services.AddMvc();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});
services.AddSwaggerGenNewtonsoftSupport(); // explicit opt-in - needs to be placed after AddSwaggerGen()DotSwashbuckle relies heavily on ApiExplorer, the API metadata layer that ships with ASP.NET Core. If you're using the AddMvc helper to bootstrap the MVC stack, then ApiExplorer will be automatically registered and SB will work without issue. However, if you're using AddMvcCore for a more paired-down MVC stack, you'll need to explicitly add the ApiExplorer service:
services.AddMvcCore()
.AddApiExplorer();Additionally, if you are using conventional routing (as opposed to attribute routing), any controllers and the actions on those controllers that use conventional routing will not be represented in ApiExplorer, which means DotSwashbuckle won't be able to find those controllers and generate Swagger operations from them. For instance:
app.UseMvc(routes =>
{
// SwaggerGen won't find controllers that are routed via this technique.
routes.MapRoute("default", "{controller=Home}/{action=Index}/{id?}");
});You must use attribute routing for any controllers that you want represented in your Swagger document(s):
[Route("example")]
public class ExampleController : Controller
{
[HttpGet("")]
public IActionResult DoStuff() { /**/ }
}Refer to the routing documentation for more information.
DotSwashbuckle consists of multiple components that can be used together or individually depending on your needs. At its core, there's a Swagger generator, middleware to expose it as JSON endpoints, and a packaged version of the swagger-ui. These 3 packages can be installed with the DotSwashbuckle.AspNetCore "metapackage" and will work together seamlessly (see Getting Started) to provide beautiful API docs that are automatically generated from your code.
Additionally, there's add-on packages (CLI tools, an alternate UI etc.) that you can optionally install and configure as needed.
| Package | Description |
|---|---|
| DotSwashbuckle.AspNetCore.Swagger | Exposes Swagger JSON endpoints. It expects an implementation of ISwaggerProvider to be registered in the DI container, which it queries to retrieve OpenAPIDocument(s) that are then exposed as serialized JSON |
| DotSwashbuckle.AspNetCore.SwaggerGen | Injects an implementation of ISwaggerProvider that can be used by the above component. This particular implementation generates OpenApiDocument(s) from your routes, controllers and models |
| DotSwashbuckle.AspNetCore.SwaggerUI | Exposes an embedded version of the swagger-ui. You specify the API endpoints where it can obtain Swagger JSON, and it uses them to power interactive docs for your API |
| Package | Description |
|---|---|
| DotSwashbuckle.AspNetCore.Annotations | Includes a set of custom attributes that can be applied to controllers, actions and models to enrich the generated Swagger |
| DotSwashbuckle.AspNetCore.Cli | Provides a command line interface for retrieving Swagger directly from a startup assembly, and writing to file |
| DotSwashbuckle.AspNetCore.Redoc | Exposes an embedded version of the Redoc UI (an alternative to swagger-ui) |
The steps described above will get you up and running with minimal setup. However, DotSwashbuckle offers a lot of flexibility to customize as you see fit. Check out the table below for the full list of options:
-
DotSwashbuckle.AspNetCore.SwaggerGen
- Assign Explicit OperationIds
- List Operations Responses
- Flag Required Parameters and Schema Properties
- Handle Forms and File Uploads
- Handle File Downloads
- Include Descriptions from XML Comments
- Provide Global API Metadata
- Generate Multiple Swagger Documents
- Omit Obsolete Operations and/or Schema Properties
- Omit Arbitrary Operations
- Customize Operation Tags (e.g. for UI Grouping)
- Change Operation Sort Order (e.g. for UI Sorting)
- Customize Schema Id's
- Override Schema for Specific Types
- Extend Generator with Operation, Schema & Document Filters
- Add Security Definitions and Requirements
- Add Security Definitions and Requirements for Bearer auth
- Inheritance and Polymorphism
By default, Swagger JSON will be exposed at the following route - "/swagger/{documentName}/swagger.json". If necessary, you can change this when enabling the Swagger middleware. Custom routes MUST include the {documentName} parameter.
app.UseSwagger(c =>
{
c.RouteTemplate = "api-docs/{documentName}/swagger.json";
})NOTE: If you're using the SwaggerUI middleware, you'll also need to update its configuration to reflect the new endpoints:
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/api-docs/v1/swagger.json", "My API V1");
})NOTE: If you also need to update the relative path that the UI itself is available on, you'll need to follow the instructions found in Change Relative Path to the UI.
If you need to set some Swagger metadata based on the current request, you can configure a filter that's executed prior to serializing the document.
app.UseSwagger(c =>
{
c.PreSerializeFilters.Add((swagger, httpReq) =>
{
swagger.Servers = new List<OpenApiServer> { new OpenApiServer { Url = $"{httpReq.Scheme}://{httpReq.Host.Value}" } };
});
});The OpenApiDocument and the current HttpRequest are both passed to the filter. This provides a lot of flexibility. For example, you can add an explicit API server based on the "Host" header (as shown), or you could inspect session information or an Authorization header and remove operations from the document based on user permissions.
By default, DotSwashbuckle will generate and expose Swagger JSON in version 3.0 of the specification, officially called the OpenAPI Specification. However, to support backwards compatibility, you can opt to continue exposing it in the 2.0 format with the following option:
app.UseSwagger(c =>
{
c.SerializeAsV2 = true;
});Virtual directories and reverse proxies can cause issues for applications that generate links and redirects, particularly if the app returns absolute URLs based on the Host header and other information from the current request. To avoid these issues, DotSwashbuckle uses relative URLs where possible, and encourages their use when configuring the SwaggerUI and Redoc middleware.
For example, to wire up the SwaggerUI middleware, you provide the URL to one or more OpenAPI/Swagger documents. This is the URL that the swagger-ui, a client-side application, will call to retrieve your API metadata. To ensure this works behind virtual directories and reverse proxies, you should express this relative to the RoutePrefix of the swagger-ui itself:
app.UseSwaggerUI(c =>
{
c.RoutePrefix = "swagger";
c.SwaggerEndpoint("v1/swagger.json", "My API V1");
});NOTE: In previous versions of the docs, you may have seen this expressed as a root-relative link (e.g. /swagger/v1/swagger.json). This won't work if your app is hosted on an IIS virtual directory or behind a proxy that trims the request path before forwarding. If you switch to the page-relative syntax shown above, it should work in all cases.
In Swagger, operations MAY be assigned an operationId. This ID MUST be unique among all operations described in the API. Tools and libraries (e.g. client generators) MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
Auto-generating an ID that matches these requirements, while also providing a name that would be meaningful in client libraries is a non-trivial task and so, DotSwashbuckle omits the operationId by default. However, if necessary, you can assign operationIds by decorating individual routes OR by providing a custom strategy.
Option 1) Decorate routes with a Name property
[HttpGet("{id}", Name = "GetProductById")]
public IActionResult Get(int id) // operationId = "GetProductById"Option 2) Provide a custom strategy
// Startup.cs
services.AddSwaggerGen(c =>
{
...
// Use method name as operationId
c.CustomOperationIds(apiDesc =>
{
return apiDesc.TryGetMethodInfo(out MethodInfo methodInfo) ? methodInfo.Name : null;
});
})
// ProductsController.cs
[HttpGet("{id}")]
public IActionResult GetProductById(int id) // operationId = "GetProductById"NOTE: With either approach, API authors are responsible for ensuring the uniqueness of operationIds across all Operations
By default, DotSwashbuckle will generate a "200" response for each operation. If the action returns a response DTO, then this will be used to generate a schema for the response body. For example ...
[HttpPost("{id}")]
public Product GetById(int id)Will produce the following response metadata:
responses: {
200: {
description: "Success",
content: {
"application/json": {
schema: {
$ref: "#/components/schemas/Product"
}
}
}
}
}
If you need to specify a different status code and/or additional responses, or your actions return IActionResult instead of a response DTO, you can explicitly describe responses with the ProducesResponseTypeAttribute that ships with ASP.NET Core. For example ...
[HttpPost("{id}")]
[ProducesResponseType(typeof(Product), 200)]
[ProducesResponseType(typeof(IDictionary<string, string>), 400)]
[ProducesResponseType(500)]
public IActionResult GetById(int id)Will produce the following response metadata:
responses: {
200: {
description: "Success",
content: {
"application/json": {
schema: {
$ref: "#/components/schemas/Product"
}
}
}
},
400: {
description: "Bad Request",
content: {
"application/json": {
schema: {
type: "object",
additionalProperties: {
type: "string"
}
}
}
}
},
500: {
description: "Server Error",
content: {}
}
}
In a Swagger document, you can flag parameters and schema properties that are required for a request. If a parameter (top-level or property-based) is decorated with the BindRequiredAttribute or RequiredAttribute, then DotSwashbuckle will automatically flag it as a "required" parameter in the generated Swagger:
// ProductsController.cs
public IActionResult Search([FromQuery, BindRequired]string keywords, [FromQuery]PagingParams pagingParams)
{
if (!ModelState.IsValid)
return BadRequest(ModelState);
...
}
// SearchParams.cs
public class PagingParams
{
[Required]
public int PageNo { get; set; }
public int PageSize { get; set; }
}In addition to parameters, DotSwashbuckle will also honor the RequiredAttribute when used in a model that's bound to the request body. In this case, the decorated properties will be flagged as "required" properties in the body description:
// ProductsController.cs
public IActionResult Create([FromBody]Product product)
{
if (!ModelState.IsValid)
return BadRequest(ModelState);
...
}
// Product.cs
public class Product
{
[Required]
public string Name { get; set; }
public string Description { get; set; }
}This controller will accept two form field values and one named file upload from the same form:
[HttpPost]
public void UploadFile([FromForm]string description, [FromForm]DateTime clientDate, IFormFile file)Important note: As per the ASP.NET Core docs, you're not supposed to decorate
IFormFileparameters with the[FromForm]attribute as the binding source is automatically inferred from the type. In fact, the inferred value isBindingSource.FormFileand if you apply the attribute it will be set toBindingSource.Forminstead, which screws upApiExplorer, the metadata component that ships with ASP.NET Core and is heavily relied on by DotSwashbuckle. One particular issue here is that SwaggerUI will not treat the parameter as a file and so will not display a file upload button, if you do mistakenly include this attribute.
ApiExplorer (the ASP.NET Core metadata component that DotSwashbuckle is built on) DOES NOT surface the FileResult type by default and so you need to explicitly tell it to with the Produces attribute:
[HttpGet("{fileName}")]
[Produces("application/octet-stream", Type = typeof(FileResult))]
public FileResult GetFile(string fileName)If you want the swagger-ui to display a "Download file" link, you're operation will need to return a Content-Type of "application/octet-stream" or a Content-Disposition of "attachement".
To enhance the generated docs with human-friendly descriptions, you can annotate controller actions and models with Xml Comments and configure DotSwashbuckle to incorporate those comments into the outputted Swagger JSON:
-
Open the Properties dialog for your project, click the "Build" tab and ensure that "XML documentation file" is checked, or add
<GenerateDocumentationFile>true</GenerateDocumentationFile>element to the<PropertyGroup>section of your .csproj project file. This will produce a file containing all XML comments at build-time.At this point, any classes or methods that are NOT annotated with XML comments will trigger a build warning. To suppress this, enter the warning code "1591" into the "Suppress warnings" field in the properties dialog or add
<NoWarn>1591</NoWarn>to the<PropertyGroup>section of your .csproj project file. -
Configure DotSwashbuckle to incorporate the XML comments on file into the generated Swagger JSON:
services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API - V1", Version = "v1" } ); var filePath = Path.Combine(System.AppContext.BaseDirectory, "MyApi.xml"); c.IncludeXmlComments(filePath); }
-
Annotate your actions with summary, remarks, param and response tags:
/// <summary> /// Retrieves a specific product by unique id /// </summary> /// <remarks>Awesomeness!</remarks> /// <param name="id" example="123">The product id</param> /// <response code="200">Product retrieved</response> /// <response code="404">Product not found</response> /// <response code="500">Oops! Can't lookup your product right now</response> [HttpGet("{id}")] [ProducesResponseType(typeof(Product), 200)] [ProducesResponseType(404)] [ProducesResponseType(500)] public Product GetById(int id)
-
You can also annotate types with summary and example tags:
public class Product { /// <summary> /// The name of the product /// </summary> /// <example>Men's basketball shoes</example> public string Name { get; set; } /// <summary> /// Quantity left in stock /// </summary> /// <example>10</example> public int AvailableStock { get; set; } /// <summary> /// The sizes the product is available in /// </summary> /// <example>["Small", "Medium", "Large"]</example> public List<string> Sizes { get; set; } }
-
Rebuild your project to update the XML Comments file and navigate to the Swagger JSON endpoint. Note how the descriptions are mapped onto corresponding Swagger fields.
NOTE: You can also provide Swagger Schema descriptions by annotating your API models and their properties with summary tags. If you have multiple XML comments files (e.g. separate libraries for controllers and models), you can invoke the IncludeXmlComments method multiple times and they will all be merged into the outputted Swagger JSON.
In addition to "PathItems", "Operations" and "Responses", which DotSwashbuckle generates for you, Swagger also supports global metadata (see https://swagger.io/specification/#oasObject). For example, you can provide a full description for your API, terms of service or even contact and licensing information:
c.SwaggerDoc("v1",
new OpenApiInfo
{
Title = "My API - V1",
Version = "v1",
Description = "A sample API to demo DotSwashbuckle",
TermsOfService = new Uri("https://tempuri.org/terms"),
Contact = new OpenApiContact
{
Name = "Joe Developer",
Email = "[email protected]"
},
License = new OpenApiLicense
{
Name = "Apache 2.0",
Url = new Uri("https://www.apache.org/licenses/LICENSE-2.0.html")
}
}
);TIP: Use IntelliSense to see what other fields are available.
With the setup described above, the generator will include all API operations in a single Swagger document. However, you can create multiple documents if necessary. For example, you may want a separate document for each version of your API. To do this, start by defining multiple Swagger docs in Startup.cs:
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API - V1", Version = "v1" });
c.SwaggerDoc("v2", new OpenApiInfo { Title = "My API - V2", Version = "v2" });
})Take note of the first argument to SwaggerDoc. It MUST be a URI-friendly name that uniquely identifies the document. It's subsequently used to make up the path for requesting the corresponding Swagger JSON. For example, with the default routing, the above documents will be available at "/swagger/v1/swagger.json" and "/swagger/v2/swagger.json".
Next, you'll need to inform DotSwashbuckle which actions to include in each document. Although this can be customized (see below), by default, the generator will use the ApiDescription.GroupName property, part of the built-in metadata layer that ships with ASP.NET Core, to make this distinction. You can set this by decorating individual actions OR by applying an application wide convention.
To include an action in a specific Swagger document, decorate it with the ApiExplorerSettingsAttribute and set GroupName to the corresponding document name (case sensitive):
[HttpPost]
[ApiExplorerSettings(GroupName = "v2")]
public void Post([FromBody]Product product)To group by convention instead of decorating every action, you can apply a custom controller or action convention. For example, you could wire up the following convention to assign actions to documents based on the controller namespace.
// ApiExplorerGroupPerVersionConvention.cs
public class ApiExplorerGroupPerVersionConvention : IControllerModelConvention
{
public void Apply(ControllerModel controller)
{
var controllerNamespace = controller.ControllerType.Namespace; // e.g. "Controllers.V1"
var apiVersion = controllerNamespace.Split('.').Last().ToLower();
controller.ApiExplorer.GroupName = apiVersion;
}
}
// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc(c =>
c.Conventions.Add(new ApiExplorerGroupPerVersionConvention())
);
...
}When selecting actions for a given Swagger document, the generator invokes a DocInclusionPredicate against every ApiDescription that's surfaced by the framework. The default implementation inspects ApiDescription.GroupName and returns true if the value is either null OR equal to the requested document name. However, you can also provide a custom inclusion predicate. For example, if you're using an attribute-based approach to implement API versioning (e.g. Microsoft.AspNetCore.Mvc.Versioning), you could configure a custom predicate that leverages the versioning attributes instead:
c.DocInclusionPredicate((docName, apiDesc) =>
{
if (!apiDesc.TryGetMethodInfo(out MethodInfo methodInfo)) return false;
var versions = methodInfo.DeclaringType
.GetCustomAttributes(true)
.OfType<ApiVersionAttribute>()
.SelectMany(attr => attr.Versions);
return versions.Any(v => $"v{v.ToString()}" == docName);
});If you're using the SwaggerUI middleware, you'll need to specify any additional Swagger endpoints you want to expose. See List Multiple Swagger Documents for more.
The Swagger spec includes a deprecated flag for indicating that an operation is deprecated and should be refrained from use. The Swagger generator will automatically set this flag if the corresponding action is decorated with the ObsoleteAttribute. However, instead of setting a flag, you can configure the generator to ignore obsolete actions altogether:
services.AddSwaggerGen(c =>
{
...
c.IgnoreObsoleteActions();
};A similar approach can also be used to omit obsolete properties from Schemas in the Swagger output. That is, you can decorate model properties with the ObsoleteAttribute and configure DotSwashbuckle to omit those properties when generating JSON Schemas:
services.AddSwaggerGen(c =>
{
...
c.IgnoreObsoleteProperties();
};You can omit operations from the Swagger output by decorating individual actions OR by applying an application wide convention.
To omit a specific action, decorate it with the ApiExplorerSettingsAttribute and set the IgnoreApi flag:
[HttpGet("{id}")]
[ApiExplorerSettings(IgnoreApi = true)]
public Product GetById(int id)To omit actions by convention instead of decorating them individually, you can apply a custom action convention. For example, you could wire up the following convention to only document GET operations:
// ApiExplorerGetsOnlyConvention.cs
public class ApiExplorerGetsOnlyConvention : IActionModelConvention
{
public void Apply(ActionModel action)
{
action.ApiExplorer.IsVisible = action.Attributes.OfType<HttpGetAttribute>().Any();
}
}
// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc(c =>
c.Conventions.Add(new ApiExplorerGetsOnlyConvention())
);
...
}The Swagger spec allows one or more "tags" to be assigned to an operation. The Swagger generator will assign the controller name as the default tag. This is important to note if you're using the SwaggerUI middleware as it uses this value to group operations.
You can override the default tag by providing a function that applies tags by convention. For example, the following configuration will tag, and therefore group operations in the UI, by HTTP method:
services.AddSwaggerGen(c =>
{
...
c.TagActionsBy(api => api.HttpMethod);
};By default, actions are ordered by assigned tag (see above) before they're grouped into the path-centric, nested structure of the Swagger spec. But, you can change the default ordering of actions with a custom sorting strategy:
services.AddSwaggerGen(c =>
{
...
c.OrderActionsBy((apiDesc) => $"{apiDesc.ActionDescriptor.RouteValues["controller"]}_{apiDesc.HttpMethod}");
};NOTE: This dictates the sort order BEFORE actions are grouped and transformed into the Swagger format. So, it affects the ordering of groups (i.e. Swagger "PathItems"), AND the ordering of operations within a group, in the Swagger output.
If the generator encounters complex parameter or response types, it will generate a corresponding JSON Schema, add it to the global components/schemas dictionary, and reference it from the operation description by unique Id. For example, if you have an action that returns a Product type, then the generated schema will be referenced as follows:
responses: {
200: {
description: "Success",
content: {
"application/json": {
schema: {
$ref: "#/components/schemas/Product"
}
}
}
}
}
However, if it encounters multiple types with the same name but different namespaces (e.g. RequestModels.Product & ResponseModels.Product), then DotSwashbuckle will raise an exception due to "Conflicting schemaIds". In this case, you'll need to provide a custom Id strategy that further qualifies the name:
services.AddSwaggerGen(c =>
{
...
c.CustomSchemaIds((type) => type.FullName);
};(See domaindrivendev#2703 for support for nested types)
Out-of-the-box, DotSwashbuckle does a decent job at generating JSON Schemas that accurately describe your request and response payloads. However, if you're customizing serialization behavior for certain types in your API, you may need to help it out.
For example, you might have a class with multiple properties that you want to represent in JSON as a comma-separated string. To do this you would probably implement a custom JsonConverter. In this case, DotSwashbuckle doesn't know how the converter is implemented and so you would need to provide it with a Schema that accurately describes the type:
// PhoneNumber.cs
public class PhoneNumber
{
public string CountryCode { get; set; }
public string AreaCode { get; set; }
public string SubscriberId { get; set; }
}
// Startup.cs
services.AddSwaggerGen(c =>
{
...
c.MapType<PhoneNumber>(() => new OpenApiSchema { Type = "string" });
};DotSwashbuckle exposes a filter pipeline that hooks into the generation process. Once generated, individual metadata objects are passed into the pipeline where they can be modified further. You can wire up custom filters to enrich the generated "Operations", "Schemas" and "Documents".
DotSwashbuckle retrieves an ApiDescription, part of ASP.NET Core, for every action and uses it to generate a corresponding OpenApiOperation. Once generated, it passes the OpenApiOperation and the ApiDescription through the list of configured Operation Filters.
In a typical filter implementation, you would inspect the ApiDescription for relevant information (e.g. route info, action attributes etc.) and then update the OpenApiOperation accordingly. For example, the following filter lists an additional "401" response for all actions that are decorated with the AuthorizeAttribute:
// AuthResponsesOperationFilter.cs
public class AuthResponsesOperationFilter : IOperationFilter
{
public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
var authAttributes = context.MethodInfo.DeclaringType.GetCustomAttributes(true)
.Union(context.MethodInfo.GetCustomAttributes(true))
.OfType<AuthorizeAttribute>();
if (authAttributes.Any())
operation.Responses.Add("401", new OpenApiResponse { Description = "Unauthorized" });
}
}
// Startup.cs
services.AddSwaggerGen(c =>
{
...
c.OperationFilter<AuthResponsesOperationFilter>();
};NOTE: Filter pipelines are DI-aware. That is, you can create filters with constructor parameters and if the parameter types are registered with the DI framework, they'll be automatically injected when the filters are instantiated
DotSwashbuckle generates a Swagger-flavored JSONSchema for every parameter, response and property type that's exposed by your controller actions. Once generated, it passes the schema and type through the list of configured Schema Filters.
The example below adds an AutoRest vendor extension (see https://github.com/Azure/autorest/blob/master/docs/extensions/readme.md#x-ms-enum) to inform the AutoRest tool how enums should be modelled when it generates the API client.
// AutoRestSchemaFilter.cs
public class AutoRestSchemaFilter : ISchemaFilter
{
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
var type = context.Type;
if (type.IsEnum)
{
schema.Extensions.Add(
"x-ms-enum",
new OpenApiObject
{
["name"] = new OpenApiString(type.Name),
["modelAsString"] = new OpenApiBoolean(true)
}
);
};
}
}
// Startup.cs
services.AddSwaggerGen(c =>
{
...
c.SchemaFilter<AutoRestSchemaFilter>();
};The example below allows for automatic schema generation of generic Dictionary<Enum, TValue> objects.
Note that this only generates the swagger; System.Text.Json is not able to parse dictionary enums by default,
so you will need a special JsonConverter, like in the .NET docs
// DictionaryTKeyEnumTValueSchemaFilter.cs
public class DictionaryTKeyEnumTValueSchemaFilter : ISchemaFilter
{
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
// Only run for fields that are a Dictionary<Enum, TValue>
if (!context.Type.IsGenericType || !context.Type.GetGenericTypeDefinition().IsAssignableFrom(typeof(Dictionary<,>)))
{
return;
}
var keyType = context.Type.GetGenericArguments()[0];
var valueType = context.Type.GetGenericArguments()[1];
if (!keyType.IsEnum)
{
return;
}
schema.Type = "object";
schema.Properties = keyType.GetEnumNames().ToDictionary(name => name,
name => context.SchemaGenerator.GenerateSchema(valueType,
context.SchemaRepository));
}
}
// Startup.cs
services.AddSwaggerGen(c =>
{
...
// These will be replaced by DictionaryTKeyEnumTValueSchemaFilter, but are needed to avoid an error.
// You will need one for every kind of Dictionary<,> you have.
c.MapType<Dictionary<MyEnum, List<string>>>(() => new OpenApiSchema());
c.SchemaFilter<DictionaryTKeyEnumTValueSchemaFilter>();
};
Once an OpenApiDocument has been generated, it too can be passed through a set of pre-configured Document Filters. This gives full control to modify the document however you see fit. To ensure you're still returning valid Swagger JSON, you should have a read through the specification before using this filter type.
The example below provides a description for any tags that are assigned to operations in the document:
public class TagDescriptionsDocumentFilter : IDocumentFilter
{
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
swaggerDoc.Tags = new List<OpenApiTag> {
new OpenApiTag { Name = "Products", Description = "Browse/manage the product catalog" },
new OpenApiTag { Name = "Orders", Description = "Submit orders" }
};
}
}NOTE: If you're using the SwaggerUI middleware, the TagDescriptionsDocumentFilter demonstrated above could be used to display additional descriptions beside each group of Operations.
In Swagger, you can describe how your API is secured by defining one or more security schemes (e.g basic, api key, oauth2 etc.) and declaring which of those schemes are applicable globally OR for specific operations. For more details, take a look at the Security Requirement Object in the Swagger spec..
In DotSwashbuckle, you can define schemes by invoking the AddSecurityDefinition method, providing a name and an instance of OpenApiSecurityScheme. For example you can define an OAuth 2.0 - implicit flow as follows:
// Startup.cs
services.AddSwaggerGen(c =>
{
...
// Define the OAuth2.0 scheme that's in use (i.e. Implicit Flow)
c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
{
Type = SecuritySchemeType.OAuth2,
Flows = new OpenApiOAuthFlows
{
Implicit = new OpenApiOAuthFlow
{
AuthorizationUrl = new Uri("/auth-server/connect/authorize", UriKind.Relative),
Scopes = new Dictionary<string, string>
{
{ "readAccess", "Access read operations" },
{ "writeAccess", "Access write operations" }
}
}
}
});
};NOTE: In addition to defining a scheme, you also need to indicate which operations that scheme is applicable to. You can apply schemes globally (i.e. to ALL operations) through the AddSecurityRequirement method. The example below indicates that the scheme called "oauth2" should be applied to all operations, and that the "readAccess" and "writeAccess" scopes are required. When applying schemes of type other than "oauth2", the array of scopes MUST be empty.
c.AddSwaggerGen(c =>
{
...
c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "oauth2" }
},
new[] { "readAccess", "writeAccess" }
}
});
})If you have schemes that are only applicable for certain operations, you can apply them through an Operation filter. For example, the following filter adds OAuth2 requirements based on the presence of the AuthorizeAttribute:
// SecurityRequirementsOperationFilter.cs
public class SecurityRequirementsOperationFilter : IOperationFilter
{
public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
// Policy names map to scopes
var requiredScopes = context.MethodInfo
.GetCustomAttributes(true)
.OfType<AuthorizeAttribute>()
.Select(attr => attr.Policy)
.Distinct();
if (requiredScopes.Any())
{
operation.Responses.Add("401", new OpenApiResponse { Description = "Unauthorized" });
operation.Responses.Add("403", new OpenApiResponse { Description = "Forbidden" });
var oAuthScheme = new OpenApiSecurityScheme
{
Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "oauth2" }
};
operation.Security = new List<OpenApiSecurityRequirement>
{
new OpenApiSecurityRequirement
{
[ oAuthScheme ] = requiredScopes.ToList()
}
};
}
}
}NOTE: If you're using the SwaggerUI middleware, you can enable interactive OAuth2.0 flows that are powered by the emitted security metadata. See Enabling OAuth2.0 Flows for more details.
services.AddSwaggerGen(c =>
{
c.AddSecurityDefinition("bearerAuth", new OpenApiSecurityScheme
{
Type = SecuritySchemeType.Http,
Scheme = "bearer",
BearerFormat = "JWT",
Description = "JWT Authorization header using the Bearer scheme."
});
c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "bearerAuth" }
},
new string[] {}
}
});
});Swagger / OpenAPI defines the allOf and oneOf keywords for describing inheritance and polymorphism relationships in schema definitions. For example, if you're using a base class for models that share common properties you can use the allOf keyword to describe the inheritance hierarchy. Or, if your serializer supports polymorphic serialization/deserialization, you can use the oneOf keyword to document all the "possible" schemas for requests/responses that vary by subtype.
By default, DotSwashbuckle flattens inheritance hierarchies. That is, for derived models, the inherited properties are combined and listed alongside the declared properties. This can cause a lot of duplication in the generated Swagger, particularly when there's multiple subtypes. It's also problematic if you're using a client generator (e.g. NSwag) and would like to maintain the inheritance hierarchy in the generated client models. To work around this, you can apply the UseAllOfForInheritance setting, and this will leverage the allOf keyword to incorporate inherited properties by reference in the generated Swagger:
Circle: {
type: "object",
allOf: [
{
$ref: "#/components/schemas/Shape"
}
],
properties: {
radius: {
type: "integer",
format: "int32",
}
},
},
Shape: {
type: "object",
properties: {
name: {
type: "string",
nullable: true,
}
},
}
If your serializer supports polymorphic serialization/deserialization and you would like to list the possible subtypes for an action that accepts/returns abstract base types, you can apply the UseOneOfForPolymorphism setting. As a result, the generated request/response schemas will reference a collection of "possible" schemas instead of just the base class schema:
requestBody: {
content: {
application/json: {
schema: {
oneOf: [
{
$ref: "#/components/schemas/Rectangle"
},
{
$ref: "#/components/schemas/Circle"
},
],
}
}
}
As inheritance and polymorphism relationships can often become quite complex, not just in your own models but also within the .NET class library, DotSwashbuckle is selective about which hierarchies it does and doesn't expose in the generated Swagger. By default, it will pick up any subtypes that are defined in the same assembly as a given base type. If you'd like to override this behavior, you can provide a custom selector function:
services.AddSwaggerGen(c =>
{
...
c.UseAllOfForInheritance();
c.SelectSubTypesUsing(baseType =>
{
return typeof(Startup).Assembly.GetTypes().Where(type => type.IsSubclassOf(baseType));
})
});NOTE: If you're using the DotSwashbuckle Annotations library, it contains a custom selector that's based on the presence of JsonDerivedType attributes on base class definitions. This way, you can use simple attributes to explicitly list the inheritance and/or polymorphism relationships you want to expose. To enable this behavior, check out the Annotations docs.
In conjunction with the oneOf and/or allOf keywords, Swagger / OpenAPI supports a discriminator field on base schema definitions. This keyword points to the property that identifies the specific type being represented by a given payload. In addition to the property name, the discriminator description MAY also include a mapping which maps discriminator values to specific schema definitions.
For example, the Newtonsoft serializer supports polymorphic serialization/deserialization by emitting/accepting a "$type" property on JSON instances. The value of this property will be the assembly qualified type name of the type represented by a given JSON instance. So, to explicitly describe this behavior in Swagger, the corresponding request/response schema could be defined as follows:
components: {
schemas: {
Shape: {
required: [
"$type"
],
type: "object",
properties: {
$type: {
type": "string"
},
discriminator: {
propertyName: "$type",
mapping: {
Rectangle: "#/components/schemas/Rectangle",
Circle: "#/components/schemas/Circle"
}
}
},
Rectangle: {
type: "object",
allOf: [
{
"$ref": "#/components/schemas/Shape"
}
],
...
},
Circle: {
type: "object",
allOf: [
{
"$ref": "#/components/schemas/Shape"
}
],
...
}
}
}
If UseAllOfForInheritance or UseOneOfForPolymorphism is enabled, and your serializer supports (and has enabled) emitting/accepting a discriminator property, then DotSwashbuckle will automatically generate the corresponding discriminator metadata on base schema definitions.
Alternatively, if you've customized your serializer to support polymorphic serialization/deserialization, you can provide some custom selector functions to determine the discriminator name and corresponding mapping:
services.AddSwaggerGen(c =>
{
...
c.UseOneOfForInheritance();
c.SelectDiscriminatorNameUsing((baseType) => "TypeName");
c.SelectDiscriminatorValueUsing((subType) => subType.Name);
});NOTE: If you're using the DotSwashbuckle Annotations library, it contains custom selector functions that are based on the presence of JsonPolymorphic and JsonDerivedType attributes on base class definitions. This way, you can use simple attributes to explicitly provide discriminator metadata. To enable this behavior, check out the Annotations docs.
By default, the Swagger UI will be exposed at "/swagger". If necessary, you can alter this when enabling the SwaggerUI middleware:
app.UseSwaggerUI(c =>
{
c.RoutePrefix = "api-docs"
...
}By default, the Swagger UI will have a generic document title. When you have multiple Swagger pages open, it can be difficult to tell them apart. You can alter this when enabling the SwaggerUI middleware:
app.UseSwaggerUI(c =>
{
c.DocumentTitle = "My Swagger UI";
...
}When enabling the middleware, you're required to specify one or more Swagger endpoints (fully qualified or relative to the UI page) to power the UI. If you provide multiple endpoints, they'll be listed in the top right corner of the page, allowing users to toggle between the different documents. For example, the following configuration could be used to document different versions of an API.
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "V1 Docs");
c.SwaggerEndpoint("/swagger/v2/swagger.json", "V2 Docs");
}The swagger-ui ships with its own set of configuration parameters, all described here https://github.com/swagger-api/swagger-ui/blob/v3.8.1/docs/usage/configuration.md#display. In DotSwashbuckle, most of these are surfaced through the SwaggerUI middleware options:
app.UseSwaggerUI(c =>
{
c.DefaultModelExpandDepth(2);
c.DefaultModelRendering(ModelRendering.Model);
c.DefaultModelsExpandDepth(-1);
c.DisplayOperationId();
c.DisplayRequestDuration();
c.DocExpansion(DocExpansion.None);
c.EnableDeepLinking();
c.EnableFilter();
c.MaxDisplayedTags(5);
c.ShowExtensions();
c.ShowCommonExtensions();
c.EnableValidator();
c.SupportedSubmitMethods(SubmitMethod.Get, SubmitMethod.Head);
c.UseRequestInterceptor("(request) => { return request; }");
c.UseResponseInterceptor("(response) => { return response; }");
});NOTE: The InjectOnCompleteJavaScript and InjectOnFailureJavaScript options have been removed because the latest version of swagger-ui doesn't expose the necessary hooks. Instead, it provides a flexible customization system based on concepts and patterns from React and Redux. To leverage this, adjust the configuration initialization with plugins or you'll need to provide a custom version of index.html as described below.
The custom index sample app demonstrates this approach, using the swagger-ui plugin system provide a custom topbar, and to hide the info component.
To tweak the look and feel, you can inject additional CSS stylesheets by adding them to your wwwroot folder and specifying the relative paths in the middleware options:
app.UseSwaggerUI(c =>
{
...
c.InjectStylesheet("/swagger-ui/custom.css");
}To customize the UI beyond the basic options listed above, you can provide your own version of the swagger-ui index.html page:
app.UseSwaggerUI(c =>
{
c.IndexStream = () => GetType().Assembly
.GetManifestResourceStream("CustomUIIndex.Swagger.index.html"); // requires file to be added as an embedded resource
});To get started, you should base your custom index.html on the default version
The swagger-ui has built-in support to participate in OAuth2.0 authorization flows. It interacts with authorization and/or token endpoints, as specified in the Swagger JSON, to obtain access tokens for subsequent API calls. See Adding Security Definitions and Requirements for an example of adding OAuth2.0 metadata to the generated Swagger.
If your Swagger endpoint includes the appropriate security metadata, the UI interaction should be automatically enabled. However, you can further customize OAuth support in the UI with the following settings below. See https://github.com/swagger-api/swagger-ui/blob/v3.10.0/docs/usage/oauth2.md for more info:
app.UseSwaggerUI(c =>
{
...
c.OAuthClientId("test-id");
c.OAuthClientSecret("test-secret");
c.OAuthRealm("test-realm");
c.OAuthAppName("test-app");
c.OAuthScopeSeparator(" ");
c.OAuthAdditionalQueryStringParams(new Dictionary<string, string> { { "foo", "bar" }});
c.OAuthUseBasicAuthenticationWithAccessCodeGrant();
});To use custom interceptors on requests and responses going through swagger-ui you can define them as javascript functions in the configuration:
app.UseSwaggerUI(c =>
{
...
c.UseRequestInterceptor("(req) => { req.headers['x-my-custom-header'] = 'MyCustomValue'; return req; }");
c.UseResponseInterceptor("(res) => { console.log('Custom interceptor intercepted response from:', res.url); return res; }");
});This can be useful in a range of scenarios where you might want to append local xsrf tokens to all requests for example:
app.UseSwaggerUI(c =>
{
...
c.UseRequestInterceptor("(req) => { req.headers['X-XSRF-Token'] = localStorage.getItem('xsrf-token'); return req; }");
});Swagger UI has a big variety of options and a mighty plugin API allowing customizations.
To customize the Swagger UI (and OAuth) configuration objects before they are passed into the Swagger UI initialization,
inject a custom JavaScript file which defines a global function with the following signature.
In many cases this feature allows to avoid using a custom index.html in your project.
/**
* @param configObject See https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
* @param oauthConfigObject See https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/
*/
function initConfig(configObject, oauthConfigObject) { }Through this mechanism any options that Swagger UI supports can be set and also plugins can be registered. Swagger UI is written with React so it can be a bit tricky to write custom components. Here a full example which adds a custom section to the parameters of all operations:
// swagger-ui.js
// https://swagger.io/docs/open-source-tools/swagger-ui/customization/plugin-api/
function configInit(config) {
if(!config.plugins) {
config.plugins = [];
}
config.plugins.push(TopbarPlugin);
}
const TopbarPlugin = (system) => {
return {
// Register an own React component
components: {
CustomOperationDetails: class CustomOperationDetails extends system.React.Component {
render() {
const hello = this.props?.operation?.get('x-hello');
if(!hello) {
return '';
}
return system.React.createElement('div',
{ className: 'hello' },
hello
);
}
}
},
wrapComponents: {
// wrap the parameters component
parameters: Original => (props => {
// get the custom React component
const CustomOperationDetails = props.getComponent('CustomOperationDetails');
// Use the non JSX React API (https://reactjs.org/docs/react-without-jsx.html)
// to create a wrapper div holding our own component and the original parameters component
return system.React.createElement('div',
{ className: "parameters-wrap"},
system.React.createElement(CustomOperationDetails, props),
system.React.createElement(Original, props)
);
})
}
}
};app.UseSwaggerUI(options = >
{
options.InjectJavascript("swagger-ui.js");
});-
Install the following Nuget package into your ASP.NET Core application.
Package Manager : Install-Package DotSwashbuckle.AspNetCore.Annotations CLI : dotnet add package DotSwashbuckle.AspNetCore.Annotations -
In the
ConfigureServicesmethod ofStartup.cs, enable annotations within in the Swagger config block:services.AddSwaggerGen(c => { ... c.EnableAnnotations(); });
Once annotations have been enabled, you can enrich the generated Operation metadata by decorating actions with a SwaggerOperationAttribute.
[HttpPost]
[SwaggerOperation(
Summary = "Creates a new product",
Description = "Requires admin privileges",
OperationId = "CreateProduct",
Tags = new[] { "Purchase", "Products" }
)]
public IActionResult Create([FromBody]Product product)ASP.NET Core provides the ProducesResponseTypeAttribute for listing the different responses that can be returned by an action. These attributes can be combined with XML comments, as described above, to include human friendly descriptions with each response in the generated Swagger. If you'd prefer to do all of this with a single attribute, and avoid the use of XML comments, you can use SwaggerResponseAttributes instead:
[HttpPost]
[SwaggerResponse(201, "The product was created", typeof(Product))]
[SwaggerResponse(400, "The product data is invalid")]
public IActionResult Create([FromBody]Product product)You can annotate "path", "query" or "header" bound parameters or properties (i.e. decorated with [FromRoute], [FromQuery] or [FromHeader]) with a SwaggerParameterAttribute to enrich the corresponding Parameter metadata that's generated by DotSwashbuckle:
[HttpGet]
public IActionResult GetProducts(
[FromQuery, SwaggerParameter("Search keywords", Required = true)]string keywords)You can annotate "body" bound parameters or properties (i.e. decorated with [FromBody]) with a SwaggerRequestBodyAttribute to enrich the corresponding RequestBody metadata that's generated by DotSwashbuckle:
[HttpPost]
public IActionResult CreateProduct(
[FromBody, SwaggerRequestBody("The product payload", Required = true)]Product product)You can annotate classes or properties with a SwaggerSchemaAttribute to enrich the corresponding Schema metadata that's generated by DotSwashbuckle:
[SwaggerSchema(Required = new[] { "Description" })]
public class Product
{
[SwaggerSchema("The product identifier", ReadOnly = true)]
public int Id { get; set; }
[SwaggerSchema("The product description")]
public string Description { get; set; }
[SwaggerSchema("The date it was created", Format = "date")]
public DateTime DateCreated { get; set; }
}NOTE: In Swagger / OpenAPI, serialized objects AND contained properties are represented as Schema instances, hence why this annotation can be applied to both classes and properties. Also worth noting, "required" properties are specified as an array of property names on the top-level schema as opposed to a flag on each individual property.
The SwaggerGen package provides several extension points, including Schema Filters (described here) for customizing ALL generated Schemas. However, there may be cases where it's preferable to apply a filter to a specific Schema. For example, if you'd like to include an example for a specific type in your API. This can be done by decorating the type with a SwaggerSchemaFilterAttribute:
// Product.cs
[SwaggerSchemaFilter(typeof(ProductSchemaFilter))]
public class Product
{
...
}
// ProductSchemaFilter.cs
public class ProductSchemaFilter : ISchemaFilter
{
public void Apply(OpenApiSchema schema, SchemaFilterContext context)
{
schema.Example = new OpenApiObject
{
[ "Id" ] = new OpenApiInteger(1),
[ "Description" ] = new OpenApiString("An awesome product")
};
}
}By default, the Swagger generator will tag all operations with the controller name. This tag is then used to drive the operation groupings in the swagger-ui. If you'd like to provide a description for each of these groups, you can do so by adding metadata for each controller name tag via the SwaggerTagAttribute:
[SwaggerTag("Create, read, update and delete Products")]
public class ProductsController
{
...
}NOTE: This will add the above description specifically to the tag named "Products". Therefore, you should avoid using this attribute if you're tagging Operations with something other than controller name - e.g. if you're customizing the tagging behavior with TagActionsBy.
If you want to use DotSwashbuckle's inheritance and/or polymorphism behavior, you can use annotations to explicitly indicate the "known" subtypes for a given base type. This will override the default selector function, which selects all subtypes in the same assembly as the base type, and therefore needs to be explicitly enabled when you enable Annotations:
// Startup.cs
services.AddSwaggerGen(c =>
{
c.EnableAnnotations(enableAnnotationsForInheritance: true, enableAnnotationsForPolymorphism: true);
});
// Shape.cs
[JsonDerivedType(typeof(Rectangle))]
[JsonDerivedType(typeof(Circle))]
public abstract class Shape
{
}If you're using annotations to explicitly indicate the "known" subtypes for a polymorphic base type, you can combine the JsonPolymorphicAttribute with the JsonDerivedTypeAttribute to provide additional metadata about the "discriminator" property, which will then be incorporated into the generated schema definition:
// Startup.cs
services.AddSwaggerGen(c =>
{
c.EnableAnnotations(enableAnnotationsForInheritance: true, enableAnnotationsForPolymorphism: true);
});
// Shape.cs
[JsonPolymorphic(TypeDiscriminatorPropertyName = "shapeType")]
[JsonDerivedType(typeof(Rectangle), "rectangle")]
[JsonDerivedType(typeof(Circle), "circle")]
public abstract class Shape
{
// Avoid using a JsonPolymorphicAttribute.TypeDiscriminatorPropertyName
// that conflicts with a property in your type hierarchy.
// Related issue: https://github.com/dotnet/runtime/issues/72170
}
[JsonConverter(typeof(JsonStringEnumConverter))]
public enum AnimalType
{
Circle,
Rectangle
}This indicates that the corresponding payload will have a "shapeType" property to discriminate between subtypes, and that property will have a value of "rectangle" if the payload represents a Rectangle type and a value of "circle" if it represents a Circle type. This detail will be described in the generated schema definition as follows:
schema: {
oneOf: [
{
$ref: "#/components/schemas/Rectangle"
},
{
$ref: "#/components/schemas/Circle"
},
],
discriminator: {
propertyName: shapeType,
mapping: {
rectangle: "#/components/schemas/Rectangle",
circle: "#/components/schemas/Circle",
}
}
}
Once your application has been setup with DotSwashbuckle (see Getting Started), you can use the DotSwashbuckle CLI tool to retrieve Swagger / OpenAPI JSON directly from your application's startup assembly, and write it to file. This can be useful if you want to incorporate Swagger generation into a CI/CD process, or if you want to serve it from static file at run-time.
It's packaged as a .NET Core Tool that can be installed and used via the dotnet SDK.
⚠️ The tool needs to load your Startup DLL and its dependencies at runtime. Therefore, you should use a version of thedotnetSDK that is compatible with your application. For example, if your app targetsnetcoreapp2.1, then you should use version 2.1 of the SDK to run the CLI tool. If it targetsnetcoreapp3.0, then you should use version 3.0 of the SDK and so on.
-
Install as a global tool
dotnet tool install -g --version 6.5.0 DotSwashbuckle.AspNetCore.Cli -
Verify that the tool was installed correctly
swagger tofile --help -
Generate a Swagger/ OpenAPI document from your application's startup assembly
swagger tofile --output [output] [startupassembly] [swaggerdoc]Where ...
- [output] is the relative path where the Swagger JSON will be output to
- [startupassembly] is the relative path to your application's startup assembly
- [swaggerdoc] is the name of the swagger document you want to retrieve, as configured in your startup class
-
In your project root, create a tool manifest file:
dotnet new tool-manifest -
Install as a local tool
dotnet tool install --version 6.5.0 DotSwashbuckle.AspNetCore.Cli -
Verify that the tool was installed correctly
dotnet swagger tofile --help -
Generate a Swagger / OpenAPI document from your application's startup assembly
dotnet swagger tofile --output [output] [startupassembly] [swaggerdoc]Where ...
- [output] is the relative path where the Swagger JSON will be output to
- [startupassembly] is the relative path to your application's startup assembly
- [swaggerdoc] is the name of the swagger document you want to retrieve, as configured in your startup class
Out-of-the-box, the tool will execute in the context of a "default" web host. However, in some cases you may want to bring your own host environment, for example if you've configured a custom DI container such as Autofac. For this scenario, the DotSwashbuckle CLI tool exposes a convention-based hook for your application.
That is, if your application contains a class that meets either of the following naming conventions, then that class will be used to provide a host for the CLI tool to run in.
public class SwaggerHostFactory, containing a public static method calledCreateHostwith return typeIHostpublic class SwaggerWebHostFactory, containing a public static method calledCreateWebHostwith return typeIWebHost
For example, the following class could be used to leverage the same host configuration as your application:
public class SwaggerHostFactory
{
public static IHost CreateHost()
{
return Program.CreateHostBuilder(new string[0]).Build();
}
}By default, the Redoc UI will be exposed at "/api-docs". If necessary, you can alter this when enabling the Redoc middleware:
app.UseRedoc(c =>
{
c.RoutePrefix = "docs"
...
}By default, the Redoc UI will have a generic document title. You can alter this when enabling the Redoc middleware:
app.UseRedoc(c =>
{
c.DocumentTitle = "My API Docs";
...
}Redoc ships with its own set of configuration parameters, all described here https://github.com/Rebilly/Redoc/blob/master/README.md#redoc-options-object. In DotSwashbuckle, most of these are surfaced through the Redoc middleware options:
app.UseRedoc(c =>
{
c.SpecUrl("/v1/swagger.json");
c.EnableUntrustedSpec();
c.ScrollYOffset(10);
c.HideHostname();
c.HideDownloadButton();
c.ExpandResponses("200,201");
c.RequiredPropsFirst();
c.NoAutoAuth();
c.PathInMiddlePanel();
c.HideLoading();
c.NativeScrollbars();
c.DisableSearch();
c.OnlyRequiredInSamples();
c.SortPropsAlphabetically();
});Using c.SpecUrl("/v1/swagger.json") multiple times within the same UseRedoc(...) will not add multiple urls.
To tweak the look and feel, you can inject additional CSS stylesheets by adding them to your wwwroot folder and specifying the relative paths in the middleware options:
app.UseRedoc(c =>
{
...
c.InjectStylesheet("/redoc/custom.css");
}It is also possible to modify the theme by using the AdditionalItems property, see https://github.com/Rebilly/Redoc/blob/master/README.md#redoc-options-object for more information.
app.UseRedoc(c =>
{
...
c.ConfigObject.AdditionalItems = ...
}To customize the UI beyond the basic options listed above, you can provide your own version of the Redoc index.html page:
app.UseRedoc(c =>
{
c.IndexStream = () => GetType().Assembly
.GetManifestResourceStream("CustomIndex.Redoc.index.html"); // requires file to be added as an embedded resource
});To get started, you should base your custom index.html on the default version