Post File in Swagger OpenAPI V3.0 and V2.0 examples

Post File in Swagger OpenAPI V30 and V20

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

how to post files in swagger openapi

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:

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



Leave a Reply

Your email address will not be published. Required fields are marked *