This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Download Microsoft Edge
More info about Internet Explorer and Microsoft Edge
Important
This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
For the current release, see the
.NET 8 version of this article
.
By
Christoph Nienaber
and
Rico Suter
Swagger
(
OpenAPI
) is a language-agnostic specification for describing REST APIs. It allows both computers and humans to understand the capabilities of a REST API without direct access to the source code. Its main goals are to:
Minimize the amount of work needed to connect decoupled services.
Reduce the amount of time needed to accurately document a service.
The two main OpenAPI implementations for .NET are
Swashbuckle
and
NSwag
, see:
Getting Started with Swashbuckle
Getting Started with NSwag
OpenAPI vs. Swagger
The Swagger project was donated to the OpenAPI Initiative in 2015 and has since been referred to as OpenAPI. Both names are used interchangeably. However, "OpenAPI" refers to the specification. "Swagger" refers to the family of open-source and commercial products from SmartBear that work with the OpenAPI Specification. Subsequent open-source products, such as
OpenAPIGenerator
, also fall under the Swagger family name, despite not being released by SmartBear.
In short:
OpenAPI is a specification.
Swagger is tooling that uses the OpenAPI specification. For example, OpenAPIGenerator and SwaggerUI.
OpenAPI specification (
openapi.json
)
The OpenAPI specification is a document that describes the capabilities of your API. The document is based on the
XML
and attribute annotations within the controllers and models. It's the core part of the OpenAPI flow and is used to drive tooling such as SwaggerUI. By default, it's named
openapi.json
. Here's an example of an OpenAPI specification, reduced for brevity:
"openapi": "3.0.1",
"info": {
"title": "API V1",
"version": "v1"
"paths": {
"/api/Todo": {
"get": {
"tags": [
"Todo"
"operationId": "ApiTodoGet",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
"post": {
"/api/Todo/{id}": {
"get": {
"put": {
"delete": {
"components": {
"schemas": {
"ToDoItem": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
"name": {
"type": "string",
"nullable": true
"isCompleted": {
"type": "boolean"
"additionalProperties": false
Swagger UI
Swagger UI
offers a web-based UI that provides information about the service, using the generated OpenAPI specification. Both Swashbuckle and NSwag include an embedded version of Swagger UI, so that it can be hosted in your ASP.NET Core app using a middleware registration call. The web UI looks like this:
Each public action method in your controllers can be tested from the UI. Select a method name to expand the section. Add any necessary parameters, and select
Try it out!
.
The Swagger UI version used for the screenshots is version 2. For a version 3 example, see
Petstore example
.
Securing Swagger UI endpoints
Call
MapSwagger().RequireAuthorization
to secure the Swagger UI endpoints. The following example secures the swagger endpoints:
using System.Security.Claims;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddAuthorization();
builder.Services.AddAuthentication("Bearer").AddJwtBearer();
var app = builder.Build();
if (app.Environment.IsDevelopment())
app.UseSwagger();
app.UseSwaggerUI();
app.UseHttpsRedirection();
var summaries = new[]
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
app.MapSwagger().RequireAuthorization();
app.MapGet("/", () => "Hello, World!");
app.MapGet("/secret", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}. My secret")
.RequireAuthorization();
app.MapGet("/weatherforecast", () =>
var forecast = Enumerable.Range(1, 5).Select(index =>
new WeatherForecast
DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
Random.Shared.Next(-20, 55),
summaries[Random.Shared.Next(summaries.Length)]
.ToArray();
return forecast;
.WithName("GetWeatherForecast")
.WithOpenApi();
app.Run();
internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
In the preceding code, the /weatherforecast endpoint doesn't need authorization, but the Swagger endpoints do.
The following Curl passes a JWT token to test the Swagger UI endpoint:
curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/swagger/v1/swagger.json
For more information on testing with JWT tokens, see Generate tokens with dotnet user-jwts.
Generate an XML documentation file at compile time.
See GenerateDocumentationFile for more information.
Next steps
Get started with Swashbuckle
Get started with NSwag
By Christoph Nienaber and Rico Suter
Swagger (OpenAPI) is a language-agnostic specification for describing REST APIs. It allows both computers and humans to understand the capabilities of a REST API without direct access to the source code. Its main goals are to:
Minimize the amount of work needed to connect decoupled services.
Reduce the amount of time needed to accurately document a service.
The two main OpenAPI implementations for .NET are Swashbuckle and NSwag, see:
Getting Started with Swashbuckle
Getting Started with NSwag
OpenAPI vs. Swagger
The Swagger project was donated to the OpenAPI Initiative in 2015 and has since been referred to as OpenAPI. Both names are used interchangeably. However, "OpenAPI" refers to the specification. "Swagger" refers to the family of open-source and commercial products from SmartBear that work with the OpenAPI Specification. Subsequent open-source products, such as OpenAPIGenerator, also fall under the Swagger family name, despite not being released by SmartBear.
In short:
OpenAPI is a specification.
Swagger is tooling that uses the OpenAPI specification. For example, OpenAPIGenerator and SwaggerUI.
OpenAPI specification (openapi.json)
The OpenAPI specification is a document that describes the capabilities of your API. The document is based on the XML and attribute annotations within the controllers and models. It's the core part of the OpenAPI flow and is used to drive tooling such as SwaggerUI. By default, it's named openapi.json. Here's an example of an OpenAPI specification, reduced for brevity:
"openapi": "3.0.1",
"info": {
"title": "API V1",
"version": "v1"
"paths": {
"/api/Todo": {
"get": {
"tags": [
"Todo"
"operationId": "ApiTodoGet",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToDoItem"
"post": {
"/api/Todo/{id}": {
"get": {
"put": {
"delete": {
"components": {
"schemas": {
"ToDoItem": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
"name": {
"type": "string",
"nullable": true
"isCompleted": {
"type": "boolean"
"additionalProperties": false
Swagger UI
Swagger UI offers a web-based UI that provides information about the service, using the generated OpenAPI specification. Both Swashbuckle and NSwag include an embedded version of Swagger UI, so that it can be hosted in your ASP.NET Core app using a middleware registration call. The web UI looks like this:
Each public action method in your controllers can be tested from the UI. Select a method name to expand the section. Add any necessary parameters, and select Try it out!.
The Swagger UI version used for the screenshots is version 2. For a version 3 example, see Petstore example.
Next steps
Get started with Swashbuckle
Get started with NSwag
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for
This product
