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/
Related
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 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
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.
How can I add individual headers on different controllers.
E.g.:
Controller Name: Controller1,
Custom header: Header1
Controller Name: Controller2,
Custom header: Header2
The headers should be displayed for all the apis under the specific controller
This can be solved by adding an OperationFilter to your swagger configuration.
First you have to provide a class that implements IOperationFilter. The Applymethod receives an Operation parameter which contains the controller name in the tagfield. When the Swagger UI is rendered, the Applymethod will be called for each method in the API. You could even provide individual parameters for each API method, as Operation also contains the operationId.
public class AddRequiredHeaderParameter : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
if (operation.parameters == null)
operation.parameters = new List<Parameter>();
if (operation.tags[0]?.CompareTo("Example") == 0)
{
operation.parameters.Add(new Parameter
{
name = "X-ExampleParam",
#in = "header",
#default = "42", // optional default value, can be omitted
type = "string",
description = "My special parameter for the example API",
required = true
});
}
else if (operation.tags[0]?.CompareTo("Whatever") == 0)
{
// add other header parameters here
}
}
}
In the debugger, with a controller named ExampleController, it looks like this:
The result in the Swagger UI is a special parameter that is only applied to the API of my Example controller:
Tell Swagger to use your OperationFilter by adding one line in the Register method of the SwaggerConfig class:
public class SwaggerConfig
{
public static void Register(HttpConfiguration config)
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
//GlobalConfiguration.Configuration
config
.EnableSwagger(c =>
{
... // omitted some lines here
c.OperationFilter<AddRequiredHeaderParameter>(); // Add this line
... // omitted some lines here
})
}
The idea to this solution is based on ShaTin's answer: How to send custom headers with requests in Swagger UI?
This is not an answer but stackoverflow wont' let me just make a comment on the solution from jps. Just wanted to add this is what I needed for my using clauses in jps's answer to get this to work in regular .net:
using Swashbuckle.Application;
using Swashbuckle.Swagger;
using System.Collections.Generic;
using System.Web.Http.Description;
I have an ASP.NET Web API app that I have versioned using namespace versioning.
For example, this method is accessible at api/v1/Location/Process:
namespace Project.Controllers.V1
{
public class LocationController : BaseController
{
[HttpsRequired, HttpGet]
public async Task<ApiResponse> Process(string sessionToken, string id)
Swagger is set up to deal with this setup using the MultipleApiVersions method:
c.MultipleApiVersions((apiDesc, version) => {
var path = apiDesc.RelativePath.Split('/');
var pathVersion = path[1];
return CultureInfo.InvariantCulture.CompareInfo.IndexOf(pathVersion, version, CompareOptions.IgnoreCase) >= 0;
},
vc => {
vc.Version("v1", "Foundbite Client API V1");
});
However when the Swagger UI is generated the methods have the full namespace and controller name in the url: api/V1.Location/Process
Anyone know how I can edit the paths Swagger will use so I can create the correct url? (Basically just need to replace that fullstop). I ideally don't want to use routing attributes.
(There is a similar question to mine here but it misses some keen points that I'd like to address.)