Add a Custom header parameter to .NET Core API in Swagger –OpenAPI

In this article, we will learn how to add a custom header parameter to .NET Core API in Swagger (OpenAPI) documentation.

Today in this article, we will cover below aspects,

Custom headers are helpful when you want to add metadata to your API requests or responses or when you need specific headers for authentication, security, or other purposes.

Documenting custom headers in Swagger ensures that developers consuming your API understand the header requirements and can use the API effectively.

In Swagger/OpenAPI, you can document and define custom headers to be used in your API requests and responses.

Step1 – Create ASP.NET Core API

Create .NET API application

Step2: Install the required NuGet package

Using CLI tool

dotnet add package Swashbuckle.AspNetCore

OR

Using PMC(package manager console)

PM> Install-Package Swashbuckle.AspNetCore -Version <version>

Approach1 – Using IOperationFilter to add a header to swagger

Create a custom class with the name of your choice ‘CustomHeaderSwaggerAttribute‘ derived from ‘IOperationFilter‘ and overriding Apply method as below,

  public class CustomHeaderSwaggerAttribute : IOperationFilter
    {
       
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
            if (operation.Parameters == null)
                operation.Parameters = new List<OpenApiParameter>();

            operation.Parameters.Add(new OpenApiParameter
            {
                Name = "X-CustomHeader",
                In = ParameterLocation.Header,
                Required = true,
                Schema = new OpenApiSchema
                {
                    Type = "string" 
                }
            });
        }

    }

The above logic will be applied globally to all APIs. You can control the same based on each API if required using attribute filter techniques.

Let’s enable this custom Operation filter in the ConfigureServices method as below,

 public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title ="MyTestService", Version = "v1", });
                c.OperationFilter<CustomHeaderSwaggerAttribute>();

                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath);

            });
        }

Please see the swagger OpenAPI documentation below,

Approach2 – Using FromHeaderAttribute to add a header to swagger

One can also use a declarative approach by using FromHeaderAttribute using FromHeader,

        [HttpPost]
        public IActionResult Weather([FromHeader(Name = "x-CustomHeader2")] string city)
        {
            return Ok();
        }

Let’s view generated swagger,

Do you have any comments or ideas or any better suggestions to share?

Please sound off your comments below.

Happy Coding !!

References:

• Swagger API Documentation in .NET Core 3.1 or .NET 5

• Add a Header parameter to .NET Core API in Swagger v2.0 specification

Please bookmark this page and share it with your friends. Please Subscribe to the blog to receive notifications on freshly published(2024) best practices and guidelines for software design and development.