i use asp.net boilerplate for my project. i updated devexpress version from 21.1.4 to 21.2.5 and made a custom WebDocumentViewerController.
public class CustomWebDocumentController :
WebDocumentViewerController
{
public
CustomWebDocumentController(IWebDocumentViewerMvcControllerService
controllerService) : base(controllerService)
{
}
}
i used this code to remove defualt DocumentViewerController in startup.sc:
services.AddMvc()
.ConfigureApplicationPartManager(x =>
{
var parts = x.ApplicationParts;
var aspNetCoreReportingAssemblyName =
typeof(WebDocumentViewerController).Assembly.GetName().Name;
var reportingPart = parts.FirstOrDefault(part => part.Name
== aspNetCoreReportingAssemblyName);
if (reportingPart != null)
{
parts.Remove(reportingPart);
}
});
the code is running but the defualtcontroller is still in list of controllers and makes swagger confiused.
how should i remove the defualt contoller?
thanks for your time.
The reason why this "ambiguous HTTP method for Action Error" pops up is because this controller 'CustomWebDocumentController' is missing the HTTP action decoration ([HttpGet],[HttpPost] etc) on top of it.
Simply decorate the controller with '[ApiExplorerSettings(IgnoreApi=true)]'. This will ultimately cause the entire controller or individual action to be omitted from the Swagger output.
Source: Exclude controllers methods from docs without using the Obsolete attribute
public class CustomWebDocumentController : WebDocumentViewerController
{
[ApiExplorerSettings(IgnoreApi = true)]
public
CustomWebDocumentController(IWebDocumentViewerMvcControllerService controllerService) : base(controllerService)
{
}
}
I'm building a REST service that will host multiple controllers (microservices). As a whole, lets call the service "Bob". So swagger displays "Bob" / "A collection of Bob Microservices". Then the controller names are listed. Right now, it just shows XYZ, ABC, etc. Is there a way to maybe have swagger show "XYZ - A collection of XYZ APIs" or something of that sort?
Seems like swagger shows the ///Summary on the methods, but not on the controllers.
If you are using Swashbuckle 4.0.x and ASP.NET Core 2.x, you may have something like this which also works by including the NuGet package for Swashbuckle.AspNetCore.Annotations.
using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Swashbuckle.AspNetCore.Annotations;
namespace MyExample.Controllers
{
/// <summary>
/// Example of a .NET Core controller based on the controller name
/// api/[controller] on ValuesController becomes api/values
/// endpoint: "/Values" from [controller] and name of controller , which is "ValuesController"
/// </summary>
[Route("[controller]")]
[ApiController]
[SwaggerTag("This is an example controller generated by ASP.NET Core 2.x")]
public class ValuesController : ControllerBase
{
...
}
Then my Startup.cs swagger code in the ConfigureServices Method looks like this, (edited to include contribution from Iain Carlin to include controller header comments) :
services.AddSwaggerGen(c =>
{
// Set Title and version
c.SwaggerDoc("v1", new Info { Title = "My Example API", Version = "v1", Description = "The API for my application" });
// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
// pick comments from classes, including controller summary comments
c.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
// _OR_ enable the annotations on Controller classes [SwaggerTag], if no class comments present
c.EnableAnnotations();
});
Then my Controller will get decorated
I was looking for a similar answer and hoping to be able to use the summary XML comments on the controller class to provide the controller description. Turns out you can do this by adding includeControllerXmlComments: true in the Swagger configuration in startup:
services.AddSwaggerGen(c =>
{
// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath, includeControllerXmlComments: true);
});
So then:
/// <summary>
/// My controller description
/// </summary>
[Route("api/[controller]")]
[ApiController]
displays as:
Is there a way to maybe have swagger show "XYZ - A collection of XYZ APIs"
Yes. Here is one of the easiest ways. The ASP.NET Core version of Swagger leverages the ApiExplorerSettings attribute. You can set the GroupName.
public class BobController
{
[ApiExplorerSettings(GroupName="XYZ - A collection of XYZ APIs")]
public IActionResult MyAction()
{
...
}
}
The group name appears in the Swagger UI with the group's actions listed as operations underneath.
Edit: Here is an idea based on SledgeHammer's comment.
Swagger ASP.NET Core uses an IApiDescriptionGroupCollectionProvider to build its description groups. We could implement our own, using the default ApiDescriptionGroupCollectionProvider for inspiration, and register our provider during Startup.ConfigureServices. Our implementation would make the ApiDescriptionGroups() method return the GroupName associated with each action's controller. Then we could put the ApiExplorerSettings attribute on each controller instead of onto each action.
You could also use SwaggerOperationAttribute for that:
public class MyController
{
[SwaggerOperation(Tags = new[] { "XYZ - A collection of XYZ APIs" })]
public IActionResult MyAction()
{
}
}
In Swashbuckle.AspNetCore version 1.0.0-rc3 the ApiExplorerSettingsAttribute is used to include an action in a specific Swagger document.
I know this is old, but just in case someone else lands here - looking for an answer for the core version - and for the sake of completeness, I'll leave another easy option. From the docs:
Customize Operation Tags (e.g. for UI Grouping)
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 particularly interesting 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);
};
Using this way you could tag your endpoints using the logic that best fits your needs. You pass the lambda to the TagActionsBy method and return the tag you want.
For the sample you provided we could do:
services.AddSwaggerGen(c =>
{
...
c.TagActionsBy(api => "XYZ - A collection of XYZ APIs");
};
Hope this helps!
There is a new attribute, replacing the old [SwaggerTag(...)] in NSwag.Annotations:
[OpenApiTag("This is name", Description = "This is description")]
Which results to:
Note, the first attribute name has to be specified, you can either keep the name the same or rename the controller.
Unfortunately, it seems that there is no easy solution for the ///summary comments to be added to the docs. This approach worked without any extra configuration.
Neat and easy method using NSwag for .NET Core 3.1. Just add the code below and you get a nice description for controllers and the APIs. Plus some description at the top of the swagger page.
Startup.cs - method: public void ConfigureServices(IServiceCollection services)
services.AddSwaggerDocument(config =>
{
config.OperationProcessors.Add(
new AspNetCoreOperationSecurityScopeProcessor("JWT"));
// Add summary to the controller
config.UseControllerSummaryAsTagDescription = true;
// Add JWT authorization option at the top
config.AddSecurity("JWT", Enumerable.Empty<string>(), new OpenApiSecurityScheme
{
Type = OpenApiSecuritySchemeType.ApiKey,
Name = "Authorization",
In = OpenApiSecurityApiKeyLocation.Header,
Description = "Type into the textbox: Bearer {your JWT Token}"
});
config.PostProcess = document =>
{
document.Info.Version = "1";
document.Info.Title = "title";
document.Info.Description = "description";
};
});
Method: public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
Add this:
//CONFIG: Configure NSwag
app.UseOpenApi();
app.UseSwaggerUi3();
Then, at the top of the controller class and methods, just add a summary, for example:
/// <summary>
/// your description
/// </summary>
[ApiController]
[Route(your route)]
public class NameController : ControllerBase
It will give a nice and clean as the live demo here: https://swagger.io/tools/swagger-ui/
I am developing a Asp.Net core 3.1 MVC web app with the web API project inside it.
Now I want to configure Swagger Documentation for the API project only, So how can I specify in the configurations to use only the web API controllers for documentation?
Configuration for swagger in startup class inside ConfigureServices method is as follows:-
services.AddSwaggerGen(option =>
{
option.SwaggerDoc("v1.0",
new OpenApiInfo
{
Title = "ProjName OpenApi",
Version = "1.0",
//Description = //get from appsettings.json
});
var xmlCommentFileName = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlCommentFilePath = Path.Combine(AppContext.BaseDirectory, xmlCommentFileName);
option.IncludeXmlComments(xmlCommentFilePath);
});
and the configuration in Configure method is as follows:-
app.UseSwagger(option =>
{
option.RouteTemplate = "docs/{documentname}/swagger.json";
});
app.UseSwaggerUI(option =>
{
option.SwaggerEndpoint("/docs/v1.0/swagger.json", "ProjName OpenApi v1.0");
option.RoutePrefix = "docs/v1.0";
option.DocumentTitle = "ProjName OpenAPI Docs";
});
The issue is that the swagger gen is looking in controllers folder, Admin & Identity Areas for generating docs, but I would rather like to configure it to Use only the controllers in WebApi Folder.
All the Controllers or Action methods which has been specified Route Attribute in those controllers also gets listed in the API Docs. How can I exclude those?
Can some one please help me out with this? I'm really stuck here.
PS: I would like to mention that I can not move the API layer into its separate project.
According to you description, I suggest you could try to create a custom filter to check if the controller name is mvc controller and then remove its route.
More details, you could refer to below codes:
Startup.cs ConfigureServices method:
services.AddSwaggerGen(option =>
{
option.SwaggerDoc("v1.0",
new OpenApiInfo
{
Title = "ProjName OpenApi",
Version = "1.0"});
option.DocumentFilter<HideInDocsFilter>();
});
HideInDocsFilter
public class HideInDocsFilter : IDocumentFilter
{
public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
{
foreach (var apiDescription in context.ApiDescriptions)
{
// replace the data to your controller name
if (apiDescription.ActionDescriptor.DisplayName.Contains("Data"))
{
var route = "/" + apiDescription.RelativePath.TrimEnd('/');
swaggerDoc.Paths.Remove(route);
}
}
}
}
Result:
Only contains WeatherForecast controller method
We were using Refit on one of your API's to create and share a Client package for that API.
ICategoryApi.cs
[Post("/category")]
Task CreateCategoryAsync([Body] CategoryCommandDto createCategoryCommandDto);
and everything was working fine with a controller like
CategoryController.cs
[ApiController]
[Route("[controller]")]
public class CategoriesController : ControllerBase
{
[HttpPost]
[ProducesResponseType((int)HttpStatusCode.Created)]
[ProducesResponseType((int)HttpStatusCode.BadRequest)]
public async Task<IActionResult> CreateCategory([FromBody] CategoryCommandDto createCategoryCommandDto)
{
//some code
}
}
The problem is that now we've added api versioning, and we choosed to version by route.
So now the endpoint /category looks like /v1/category and we will create a /v2/category soon.
Is there a way to configure refit (through attributes or similar) for it to understand my versioned routes?
I want to avoid having to write a new client for every new version of the API and including the version in the endpoint route like
ICategoryApiV1.cs
[Post("/v1/category")]
Task CreateCategoryAsync([Body] CategoryCommandDto createCategoryCommandDto);
Imagine that the client is bigger and has a lot of methods, not just one. Also not all the methods may change between versions.
You can achieve this in a different way:
1) Use like an argument from method;
ICategoryApiV1.cs
[Post("/{v}/category")]
Task CreateCategoryAsync([Body] CategoryCommandDto createCategoryCommandDto, [AliasAs("v")]int version = 1);
2) Define a property inside of CategoryCommandDto;
public class CategoryCommandDto
{
// Properties can be read-only and [AliasAs] isn't required
public int v { get { return 1; } }
.....
}
3) Define a baseUrl for httpClient during ICategoryApi creation
services.AddRefitClient<ICategoryApi>()
.ConfigureHttpClient(c => c.BaseAddress = new Uri($"https://api.example.com/{version}"));
4) Or if you need some advanced calculation you can add a custom HttpHandler and configure inside yours client.
services.AddRefitClient<ICategoryApi>(settings)
.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://api.example.com"));
.AddHttpMessageHandler<VersionHandler>()
I'm currently upgrading a project from ASP.NET WebAPI 5.2.6 (OWIN) to ASP.NET Core 2.1.1 (Kestrel).
Our project is a single page application and we communicate via WebAPI with the client. Therefore I wanted to annotate the controllers wit the new ApiController attribute.
Unfortunately it seems that the binding source parameter inference isn't working as expected (at least for me). I assumed based on the docs, that complex types (e.g. my LoginRequest) are inferred as [FromBody].
Code (Controller & Startup)
// AccountController.cs
[Route("/account"), ApiController]
public class AccountController : ControllerBase
{
[HttpPost("backendLogin"), AllowAnonymous]
public async Task<ActionResult<LoginResponse>> BackendLogin(LoginRequest lr)
{
await Task.CompletedTask.ConfigureAwait(false); // do some business logic
return Ok(new LoginResponse {UserId = "123"});
}
// Models
public class LoginRequest {
public string Email { get; set; }
public string Password { get; set; }
}
public class LoginResponse {
public string UserId { get; set; }
}
}
// Startup.cs
public void ConfigureServices(IServiceCollection services) {
services.AddMvcCore()
.AddJsonFormatters(settings => {
settings.DateTimeZoneHandling = DateTimeZoneHandling.Utc;
settings.DateFormatHandling = DateFormatHandling.IsoDateFormat;
settings.ContractResolver = new CamelCasePropertyNamesContractResolver();
})
.SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
services.Configure<ApiBehaviorOptions>(options => {
// options.SuppressConsumesConstraintForFormFileParameters = true;
// options.SuppressInferBindingSourcesForParameters = true;
// options.SuppressModelStateInvalidFilter = true;
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env) {
if (env.IsDevelopment()) {
app.UseDeveloperExceptionPage();
}
app.UseMvc();
}
Problem
Calling the controller from the client via Ajax call (Content-Type: application/x-www-form-urlencoded;) results in a 400 (bad request) response, with content {"":["The input was not valid."]}. On the server I get the following trace output:
Microsoft.AspNetCore.Mvc.Infrastructure.ObjectResultExecutor: Information: Executing ObjectResult, writing value of type 'Microsoft.AspNetCore.Mvc.SerializableError'.
If I change the options.SuppressInferBindingSourcesForParameters in ConfigureServices to true, it seems to work. This is strange, since this setting should disable the binding inference or have I misconceived something? Is this a bug in ASP.NET core or am I missing something?
Btw. it also works if I ommit the ApiController attribute, but I guess this is not the real solution to this problem.
Furthermore I would be happy if I don't need to change anything on the client side (adding headers, change content types, ...), because there are a lot of Ajax calls out there and I just want to upgrade the server side components.
I also asked this question on the official ASP.NET Core MVC repo.
One of the members (pranavkm) came back with an answer, which I will just quote here:
ApiController is designed for REST-client specific scenarios and isn't designed towards browser based (form-urlencoded) requests. FromBody assumes JSON \ XML request bodies and it'll attempt to serialize it, which is not what you want with form url encoded content. Using a vanilla (non-ApiController) would be the way to go here.
So for now I will omit the [ApiController] attribute.
In a later step I may change the client calls to use a JSON body, so I can readd the attribute.