Add Custom Parameters In Swagger Using ASP.NET Core 3.1

Background

 
Web APIs have some common parameters in a project, mabybe those paramters should be passed via header or query, etc.
 
For example, there is a Web API url, https://yourdomain.com/api/values, and when we access this Web API, we should add timestamp, nonce and sign three parameters in the query.
 
It means that the url must be https://yourdomain.com/api/values?timestamp=xxx&nonce=yyy&sign=zzz
 
Most of the time, we will use Swagger as our document. How can we document those parameters in Swagger without adding them in each action?
 
Here I will use ASP.NET Core 3.1 to introduce the concept.
 

How to do this?

 
Create a new Web API project, and edit the csproj file, add the following content in it.
  1. <ItemGroup>  
  2.     <PackageReference Include="Swashbuckle.AspNetCore" Version="5.0.0" />  
  3. </ItemGroup>  
  4.   
  5. <PropertyGroup>  
  6.     <GenerateDocumentationFile>true</GenerateDocumentationFile>  
  7.     <NoWarn>$(NoWarn);1591</NoWarn>  
  8. </PropertyGroup>  
Swashbuckle provides a feature named operation filter that can help us to do that job.
 
We can add those three additional parameters in our custom operation filter, so that we do not need to add them in each action.
 
Here is the sample code demonstration.
  1. using Microsoft.AspNetCore.Mvc.Controllers;  
  2. using Microsoft.OpenApi.Models;  
  3. using Swashbuckle.AspNetCore.SwaggerGen;  
  4. using System.Collections.Generic;  
  5.   
  6. public class AddCommonParameOperationFilter : IOperationFilter  
  7. {  
  8.     public void Apply(OpenApiOperation operation, OperationFilterContext context)  
  9.     {  
  10.         if (operation.Parameters == null) operation.Parameters = new List<OpenApiParameter>();  
  11.   
  12.         var descriptor = context.ApiDescription.ActionDescriptor as ControllerActionDescriptor;  
  13.   
  14.         if (descriptor != null && !descriptor.ControllerName.StartsWith("Weather"))  
  15.         {  
  16.             operation.Parameters.Add(new OpenApiParameter()  
  17.             {  
  18.                 Name = "timestamp",  
  19.                 In = ParameterLocation.Query,  
  20.                 Description = "The timestamp of now",  
  21.                 Required = true  
  22.             });  
  23.   
  24.             operation.Parameters.Add(new OpenApiParameter()  
  25.             {  
  26.                 Name = "nonce",  
  27.                 In = ParameterLocation.Query,  
  28.                 Description = "The random value",  
  29.                 Required = true  
  30.             });  
  31.   
  32.             operation.Parameters.Add(new OpenApiParameter()  
  33.             {  
  34.                 Name = "sign",  
  35.                 In = ParameterLocation.Query,  
  36.                 Description = "The signature",  
  37.                 Required = true  
  38.             });  
  39.         }  
  40.     }  
  41. }  
NOTE 
For showing the difference, we only add those parameters whose controller name does not start with Weather.
 
By the way, if you have any other parameters or conditions, add them yourself.
 
Then, we will configure Swagger in Startup class.
  1. public class Startup  
  2. {  
  3.     public void ConfigureServices(IServiceCollection services)  
  4.     {  
  5.         services.AddSwaggerGen(c =>  
  6.         {  
  7.             // sepcify our operation filter here.  
  8.             c.OperationFilter<AddCommonParameOperationFilter>();  
  9.   
  10.             c.SwaggerDoc("v1"new OpenApiInfo  
  11.             {  
  12.                 Version = "v1.0.0",  
  13.                 Title = $"v1 API",  
  14.                 Description = "v1 API",  
  15.                 TermsOfService = new Uri("https://www.c-sharpcorner.com/members/catcher-wong"),  
  16.                 Contact = new OpenApiContact  
  17.                 {  
  18.                     Name = "Catcher Wong",  
  19.                     Email = "catcher_hwq@outlook.com",  
  20.                 },  
  21.                 License = new OpenApiLicense  
  22.                 {  
  23.                     Name = "Apache-2.0",  
  24.                     Url = new Uri("https://www.apache.org/licenses/LICENSE-2.0.html")  
  25.                 }  
  26.             });  
  27.         });  
  28.   
  29.         // other....  
  30.     }  
  31.   
  32.     public void Configure(IApplicationBuilder app, IWebHostEnvironment env)  
  33.     {  
  34.         app.UseSwagger(c =>  
  35.         {  
  36.         });  
  37.         app.UseSwaggerUI(c =>  
  38.         {  
  39.             c.SwaggerEndpoint("/swagger/v1/swagger.json""v1 API");  
  40.         });  
  41.   
  42.         // other....  
  43.     }  
  44. }  
Here is the result.
 
The controller name that doesn't start with `Weather` will contain those three parameters.
 
 
The controller name starting with `Weather` will not contain those three parameters.
 
 
Here is the source code you can find in my GitHub page.

Summary

 
This article showed you a sample of how to add custom request parameters in Swagger using ASP.NET Core 3.1 and Swashbuckle.AspNetCore 5.0.0.
 
I hope this will help you!