Today in this article, we will learn how to Post File in Swagger OpenAPI V3.0 and V2.0 examples using OpenAPI Specification or Swagger specifications.

Swagger or Open API specification provides the advantage of understanding the REST services easily (especially if developers are consuming any new API ) plus helps provide easy documentation and details of capabilities given Service/API owns.

We will cover below in today’s article,

Swagger 2.0 JSON schema – Upload/Post file

Swagger 2.0 JSON schema defines the form parameter like in:formData with type as a file. Below are two fields that can be used to specify files within swagger 3.0 specifications,

• Field Name: consumes

• Value : “multipart/form-data”

Also

• Field Name “parameters” can be defined with the below value,

            "in": "formData",
            "name": "file",
            "type": "file"

Swagger 2.0 Upload single file

Below is OpenAPI V3.0 JSON schema definition for the image file,

{
  "swagger": "2.0",
  "info": {
    "title": "TheCodeBuzz",
    "version": "v1"
  },
  "paths": {
    "/WeatherForecast/UploadFile": {
      "post": {
        "tags": [
          "WeatherForecast"
        ],
        "consumes": [
          "multipart/form-data"
        ],
        "parameters": [
          {
            "in": "formData",
            "name": "file",
            "type": "file"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  }
}

Swagger 2.0 Upload multiple files

Below is OpenAPI V3.0 JSON schema definition for the image file,

Example

{
  "swagger": "2.0",
  "info": {
    "title": "TheCodeBuzz",
    "version": "v1"
  },
  "paths": {
    "/WeatherForecast/UploadFileMulti": {
      "post": {
        "tags": [
          "WeatherForecast"
        ],
        "consumes": [
          "multipart/form-data"
        ],
        "parameters": [
          {
            "in": "formData",
            "name": "files",
            "type": "array",
            "items": {
              "format": "binary",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  }
}

OpenAPI 3.0 JSON schema – Upload/Post file

As per OpenAPI 3.0 specification files are defined as binary strings, that is,

  "file": {
          "type": "string",
          "format": "binary",
          "nullable": true
         }

We will cover how to upload single or multiple files with the example of swagger/open API JSON

OpenAPI 3.0 swagger Upload single file

Below is OpenAPI V3.0 JSON schema definition for the single file,

Example

{
  "openapi": "3.0.1",
  "info": {
    "title": "TheCodeBuzz",
    "version": "v1"
  },
  "paths": {
    "/WeatherForecast/UploadFile": {
      "post": {
        "tags": [
          "WeatherForecast"
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "nullable": true
                  }
                }
              },
              "encoding": {
                "file": {
                  "style": "form"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  },
  "components": { }
}

OpenAPI 3.0 swagger Upload multiple files

As per OpenAPI 3.0 specification files are defined as binary strings, that is,

"files": {
            "type": "array",
            "items": 
             {
                "type": "string",
                "format": "binary"
             },
             "nullable": true
          }

Below is OpenAPI V3.0 JSON schema definition for the file where swagger can let you upload multiple files at a time.

Example

{
  "openapi": "3.0.1",
  "info": {
    "title": "TheCodeBuzz",
    "version": "v1"
  },
  "paths": {
    "/WeatherForecast": {
      "post": {
        "tags": [
          "WeatherForecast"
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "files": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "nullable": true
                  }
                }
              },
              "encoding": {
                "files": {
                  "style": "form"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  },
  "components": { }
}

References:

• OAuth2 Authentication in OpenAPI Swagger ASP.NET Core

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

Please sound off your comments below.

Happy Coding !!

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

The post Post File in Swagger OpenAPI V3.0 and V2.0 examples first appeared on TheCodeBuzz.

Today in this article, we will see a few easy-to-use techniques to Convert Swagger 2.0 To OpenAPI 3.1

We shall cover the below aspects of the article,

We will generate Open-definition JSON using 2.0 schema and 3.0 schema specifications.

Using Online Tooling for OpenAPI JSON Conversion

https://editor.swagger.io/

The above conversion will give you,

openapi: 3.0.1
info:
  title: Swagger Petstore
  description: 'This is a sample server Petstore server.  You can find out more about     Swagger
    at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).      For
    this sample, you can use the api key `special-key` to test the authorization     filters.'
  termsOfService: http://swagger.io/terms/
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
externalDocs:
  description: Find out more about Swagger
  url: http://swagger.io
servers:
- url: https://petstore.swagger.io/v2
- url: http://petstore.swagger.io/v2
tags:
- name: pet
  description: Everything about your Pets
  externalDocs:
    description: Find out more
    url: http://swagger.io
- name: store
  description: Access to Petstore o

Using API – Swagger Converter

If you have access to the below link,

https://converter.swagger.io/

The above POST route can be executed via Swagger for POSTMAN or SOAP UI.

How to Convert Swagger 3.1 to 2.0 in ASP.NET Core

If you already have API based on .NET core 3.1 or above supporting OpenApi then it’s very easy to create an OpenAPI v2 definition using the below code,

Above using SerializeAsV2 set as true convert and generates the swagger.json for Swagger 2.0 definition.

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

Please sound off your comments below.

Happy Coding !!

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

The post How To Convert Swagger 2.0 To OpenAPI 3.1 first appeared on TheCodeBuzz.

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 (2025) best practices and guidelines for software design and development.

The post How to Add a Header Parameter to .NET Core API in Swagger first appeared on TheCodeBuzz.

Today in this article, we shall show how to perform upload Files in Swagger UI using OpenAPI Specification V3.0.

We already looked at the approach of using IFormFile inbuilt support for Upload.

Today we will see how to handle the file Upload using the IOperationFilter interface as well.

Today in this article, we will cover below aspects,

Swagger or Open API specification provides the advantage of understanding the REST services easily (especially if developers are consuming any new API ) plus helps provide easy documentation and details of capabilities given Service/API owns.

Prerequisites

Before we see IOperationFilter usage, I recommend you to visit the below article to enable Swagger API definition in simple 2-3 steps,

• Add Swagger API Documentation in ASP.NET Core

IOperationFilter for Swagger upload file

IOperationFilter is a very useful interface and provides better control on how you want to define or customize the swagger UI behavior.

In OpenAPI 3.0 schema representation can be depicted as below,

For images/png,

requestBody:
  content:
    image/png:
      schema:
        type: string
        format: binary

• requestBody – The schema represents this keyword for request payload containing a file.

• content – specify the request media type. Example  image/png or application/octet-stream.

• schema – For file Files use a type as string schema and format as binary or base64.

Please implement the interface as below by overriding the Apply() method supporting OpenAPI specs.

Let’s define the code per the above specification,

public class FileOperationFilter : IOperationFilter
    {
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
            operation.RequestBody = new OpenApiRequestBody
            {
                Description = "upload file ",
                Content = new Dictionary<String, OpenApiMediaType>
                {
                    {
                        "multipart/form-data", new OpenApiMediaType
                        {
                            Schema = new OpenApiSchema
                            {
                                Type = "object",
                                Required = new HashSet<String>{ "file" },
                                Properties = new Dictionary<String, OpenApiSchema>
                                {
                                    {
                                        "file", new OpenApiSchema()
                                        {
                                            Type = "string",
                                            Format = "binary"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            };

        }
    }
}

For all other file types – Use Multipart requests

requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                orderId:
                  type: integer
                userId:
                  type: integer
                fileName:
                  type: string
                  format: binary

The next steps are to register the above Filter interface within the API pipeline as below,

       
          services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "TheCodeBuzz", Version = "v1" });
               
                c.ResolveConflictingActions(x => x.First());
                c.OperationFilter<FileOperationFilter>();
            });

Now choose file button will be visible on Swagger UI for performing Swagger UI file upload

Below is a simple API method. We are not using IFormFile but still, we can add the Upload file support to the Swagger definition

        [HttpPost]
        public Task UploadFile()
        {
            return Task.CompletedTask;
        }

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

Please sound off your comments below.

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

The post Upload Files in Swagger UI IOperationFilter first appeared on TheCodeBuzz.