Swashbuckle does not display the API correctly - asp.net-core

Swashbuckle was used in my project, I followed the documentation, but at the end an error was displayed.
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "ToDo API",
Description = "A simple example ASP.NET Core Web API",
TermsOfService = new Uri("https://example.com/terms"),
Contact = new OpenApiContact
{
Name = "Shayne Boyer",
Email = string.Empty,
Url = new Uri("https://twitter.com/spboyer"),
},
License = new OpenApiLicense
{
Name = "Use under LICX",
Url = new Uri("https://example.com/license"),
}
});
});
app.UseSwagger(c =>
{
c.SerializeAsV2 = true;
});
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
What did i do wrong? Thanks for the help!

I have encountered this problem before, and I can reproduce your problem, but I am not sure if this is your problem.
All configurations follow the official documentation:
Get started with Swashbuckle and ASP.NET Core
Then the reason for this error is that you must specify the request method, you need to add [HttpGet], [HttpPost], etc. to the method, and you can view the API through Swagger UI,like this:
[ApiController]
public class HomeController : Controller
{
[HttpGet]
[Route("test")]
public string Test()
{
return "Test";
}
}
Result:
If the above method cannot be solved, can you post your specific error message?

Related

ASP.NET Core API: Authentication popup is not showing up in Swagger UI

I have an ASP.NET Core Web API with Swagger integrated using Swashbuckle. I have successfully integrated authorization on Swagger UI using an operation filter, because I do not want to show padlock for anonymous APIs.
.OperationFilter<AuthorizeFilter>()
Inside the filter, I have registered basic auth security requirement for Swagger UI.
My problem is, even though authentication is happening in APIs on Swagger UI, I no longer see that nice authentication popup which is giving when click on the padlock icon.
Could someone answer, why I am not seeing the auth popup now?
Assuming you have some endpoints that protected with [Authorize] attribute (can also be put on the controller).
[Route("")]
public class HelloController : ControllerBase
{
[Authorize]
[HttpGet("secure")]
public IActionResult GetSomethingPrivate()
{
return Ok("secret");
}
[HttpGet("public")]
public IActionResult GetSomethingPublic()
{
return Ok("hey");
}
}
You need to define a security scheme suitable for your needs. But do not require it globally, instead add it inside an operation filter. Here I've added a simple token auth:
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "ApiPlayground", Version = "v1" });
c.AddSecurityDefinition("token", new OpenApiSecurityScheme
{
Type = SecuritySchemeType.ApiKey,
In = ParameterLocation.Header,
Name = HeaderNames.Authorization,
Scheme = "Bearer"
});
// dont add global security requirement
// c.AddSecurityRequirement(/*...*/);
c.OperationFilter<SecureEndpointAuthRequirementFilter>();
});
}
And here's the operation filter which references the token auth scheme we've just created. It checks if the endpoint needs authentication, then adds the requirement.
internal class SecureEndpointAuthRequirementFilter : IOperationFilter
{
public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
if (!context.ApiDescription
.ActionDescriptor
.EndpointMetadata
.OfType<AuthorizeAttribute>()
.Any())
{
return;
}
operation.Security = new List<OpenApiSecurityRequirement>
{
new OpenApiSecurityRequirement
{
[new OpenApiSecurityScheme
{
Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "token" }
}] = new List<string>()
}
};
}
}
When you run the app, it works as you expect:
So does the auth popup:
Bonus: using basic auth
Define a new security scheme with following values:
public void ConfigureServices(IServiceCollection services)
{
// ...
services.AddSwaggerGen(c =>
{
// ...
// basic auth scheme (username + password)
c.AddSecurityDefinition("basic", new OpenApiSecurityScheme
{
Type = SecuritySchemeType.Http,
Scheme = "basic"
});
// dont add global security requirement
// c.AddSecurityRequirement(/*...*/);
c.OperationFilter<SecureEndpointAuthRequirementFilter>();
});
}
Then update the operation filter to reference basic auth scheme:
internal class SecureEndpointAuthRequirementFilter : IOperationFilter
{
public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
if (!context.ApiDescription
.ActionDescriptor
.EndpointMetadata
.OfType<AuthorizeAttribute>()
.Any())
{
return;
}
operation.Security = new List<OpenApiSecurityRequirement>
{
new OpenApiSecurityRequirement
{
[new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "basic" // <-- changed "token" -> "basic"
}
}] = new List<string>()
}
};
}
}
here's how the auth popup looks:
After logging in, requests include the correct Authorization header.
In my case, I am using JWT Token Authentication with .NET Core API. I Configure the swagger with the authorization token using the below code. This code will add global security requirements.
In Startup Class ConfigureServices Method.
//Swagger Configuration
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
{
Title = "API",
Version = "v2",
Description = "Your Api Description"
});
options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
Description = "JWT Authorization header using the Bearer scheme (Example: 'Bearer 12345abcdef')",
Name = "Authorization",
In = ParameterLocation.Header,
Type = SecuritySchemeType.ApiKey,
Scheme = "Bearer"
});
options.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
}
},
Array.Empty<string>()
}
});
});
And In Configure Method
app.UseSwagger();
app.UseSwaggerUI(options =>
{
options.SwaggerEndpoint("/swagger/v1/swagger.json", "API");
});
After running the API project Authorize button will appear on the right side. On Click the authorize button Authorization popup open and then pass the token in the text box with 'Bearer token'.
Authorization working fine for me.
the Abdusco's answer is true but modify the Apply method like this for AllowAnonymousAttribute Methods in Authorized Controllers
if (!context.ApiDescription
.ActionDescriptor
.EndpointMetadata
.OfType<AuthorizeAttribute>()
.Any() || context.ApiDescription
.ActionDescriptor
.EndpointMetadata
.OfType<AllowAnonymousAttribute>()
.Any())
{
return;
}

Swashbuckle UI not displaying Security Scheme Description OAuth2

I'm trying to add a security scheme to my swagger UI page and it's getting added successfully, however, my description is not rendering or being shown at all on the UI page. I want it to display successfully since I will switch this code to be an IOperationFilter and have the description vary by endpoint. For now, though, this is my code for AddSwaggerGen:
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo
{
Title = "MyAPI",
Version = "v1"
});
options.EnableAnnotations(true);
options.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
{
Description = "This is my description that's not showing", // I want this to display on the UI
Type = SecuritySchemeType.OAuth2,
Flows = new OpenApiOAuthFlows
{
ClientCredentials = new OpenApiOAuthFlow
{
TokenUrl = new Uri("/token", UriKind.Relative)
}
}
});
options.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
},
Scheme = "oauth2",
Name = "Bearer",
In = ParameterLocation.Header
},
new List<string>()
}
});
});
This is my available authorizations that's generated in the UI:
I would assume my description should go where it's describing scopes like it does for JWT. Am I missing a configuration? I am using Swashbuckle.AspNetCore 5.0.0
This is a known issue with Swagger UI:
https://github.com/swagger-api/swagger-ui/issues/5230

How to setup a swagger API login with authorize button in asp.net web api?

I have an asp.net web api project integrated with swagger ui. I am new in swagger.I installed all required OWIN packages for authentication.It works fine with postman but when i give authorize attribute in any controller it's not working in swagger.
How can i make a login panel for authentication in swagger and how to add the bearer+access_token automatically with every request in swagger after successful login?
Thanx in advance
Here is what I did in a .net core project (2.2). This might help you in setting up authentication with swagger. I'm using swashbackle and Microsoft.OpenApi:
1-Add authentication Support:
services.AddAuthentication("ApiKey").AddScheme<AuthenticationSchemeOptions, ApiKeyAuth>("ApiKey", null);
2-Add this in the AddSwaggerGen in the ConfigureServices method:
setup.AddSecurityDefinition("ApiKey", new OpenApiSecurityScheme
{
Type = SecuritySchemeType.ApiKey,
Name = "ApiKey",
In = ParameterLocation.Header,
Description = "Please enter the API Key provided to you"
});
setup.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference {
Type = ReferenceType.SecurityScheme,
Id = "ApiKey" }
}, new List<string>() }
});
3-Create your authentication handler:
public class ApiKeyAuth : AuthenticationHandler<AuthenticationSchemeOptions>
{
public ApiKeyAuth(
IOptionsMonitor<AuthenticationSchemeOptions> options,
ILoggerFactory logger,
UrlEncoder encoder,
ISystemClock clock)
: base(options, logger, encoder, clock)
{
}
protected override Task<AuthenticateResult> HandleAuthenticateAsync()
{
if (!Request.Headers.ContainsKey("ApiKey"))
{
return Task.FromResult(AuthenticateResult.Fail("Missing ApiToken"));
}
try
{
var identity = new ClaimsIdentity( new List<Claim>() { new Claim(ClaimTypes.Sid, "1") },Scheme.Name);
var principal = new ClaimsPrincipal(identity);
var ticket = new AuthenticationTicket(principal, Scheme.Name);
return Task.FromResult(AuthenticateResult.Success(ticket));
}
catch (Exception)
{
return Task.FromResult(AuthenticateResult.Fail("Invalid Authentication Failed"));
}
}
}
you need to implement this properly since this a testing code.
As a result, you should see a new Authorize button appearing on the UI:
The authorize dialog box should look like this:
Hope this helps!
The ApiKeyAuth class is not called.
I have added [Authorize] to the controller.
Added this code to StartUp.
services.AddAuthentication("ApiKey").AddScheme("ApiKey", null);
Please add below code in Program file to authorize button on swagger page
builder.Services.AddSwaggerGen(option =>{
option.SwaggerDoc("v1", new OpenApiInfo { Title = "Portal API", Version = "v1" });
option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
In = ParameterLocation.Header,
Description = "Please enter a valid token",
Name = "Authorization",
Type = SecuritySchemeType.Http,
BearerFormat = "JWT",
Scheme = "Bearer"
});
option.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type=ReferenceType.SecurityScheme,
Id="Bearer"
}
},
new string[]{}
}
});
});

Asp.net core swagger not found and server error

I have installed Swashbuckle.AspNetCore version 4.0.1 and tried all solutions and ways. Maybe this is duplicate it's not working in IIS.
I always get not found error or internal server error.
This is my Startup.cs.
// Configure Services
services.AddSwaggerGen(x =>
{
x.SwaggerDoc("v1", new Info { Title = "Shop API", Version = "v1" });
});
// Configure
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
//c.RoutePrefix = string.Empty;
});
app.UseMvc();
Did anybody tried latest version?
I'm using the same version as your. Mine below config look like this
ConfigureServices
// Register the Swagger generator, defining one or more Swagger documents
services.AddMvc();
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "Awesome CMS Core API V1",
Contact = new Contact { Name = "Tony Hudson", Email = "", Url = "https://github.com/ngohungphuc" }
});
c.SwaggerDoc("v2", new Info
{
Version = "v2",
Title = "Awesome CMS Core API V2",
Contact = new Contact { Name = "Tony Hudson", Email = "", Url = "https://github.com/ngohungphuc" }
});
c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
});
Configure
// Enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();
// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint($"/swagger/v1/swagger.json", "Awesome CMS Core API V1");
c.SwaggerEndpoint($"/swagger/v2/swagger.json", "Awesome CMS Core API V2");
});
app.UseMvc(routes =>
{
routes.MapRoute(
name: "default",
template: "{controller=Home}/{action=Index}/{id?}");
});
}
I'm just having 2 API version so it's not important in your case
Make sure your middleware are in correct order like mine
Please let me know if you have any problem

Incorrect link in Swagger

I am using the ASP.NET Core 2.0 with Swashbuckle.AspNetCore (2.4.0)
in Startup ConfigureServices
services.AddSwaggerGen(c =>
{
c.OperationFilter<AuthorizationHeaderParameterOperationFilter>();
c.SwaggerDoc("v1", new Info
{
Version = "v1",
Title = "Library API",
Description = "ASP.NET Core Web API",
TermsOfService = "None",
Contact = new Contact
{
Name = "my name",
Email = "myname#mywebsite"
}
});
});
});
in Startup configure
app.UseSwagger(c =>
{
c.RouteTemplate =
"api-docs/{documentName}/swagger.json";
});
app.UseSwaggerUI(c =>
{
c.RoutePrefix = "api-docs";
c.SwaggerEndpoint("v1/swagger.json", "Api v1");
});
public class AuthorizationHeaderParameterOperationFilter : IOperationFilter
{
public void Apply(Operation operation, OperationFilterContext context)
{
var filterPipeline = context.ApiDescription.ActionDescriptor.FilterDescriptors;
var isAuthorized = filterPipeline.Select(filterInfo => filterInfo.Filter).Any(filter => filter is AuthorizeFilter);
var allowAnonymous = filterPipeline.Select(filterInfo => filterInfo.Filter).Any(filter => filter is IAllowAnonymousFilter);
if (isAuthorized && !allowAnonymous)
{
if (operation.Parameters == null)
operation.Parameters = new List<IParameter>();
operation.Parameters.Add(new NonBodyParameter
{
Name = "Authorization",
In = "header",
Description = "access token",
Required = true,
Type = "string"
});
}
}
}
which looks like this
however the links go to the url
about:blank
How do I set the v1/swagger.json link and the Terms of service link to go to the right place?
Use c.SwaggerEndpoint("./v1/swagger.json", "Api v1");
It's looks like a bug that relative path (without '/') renders empty link but swagger.json is available and all works.
I use relative path to work properly with reverse proxies but this is other story...