Openapi-specification: type: file is not allowed in body parameter

Created on 19 Jun 2017 · 7Comments · Source: OAI/OpenAPI-Specification

An additional primitive data type "file" is used by the Parameter Object and the Response Object to set the parameter type or the response as being a file.

The JSON schema for OpenAPI 2.0 allows type: file in the schema for a response body.

        "schema": {
          "oneOf": [
            {
              "$ref": "#/definitions/schema"
            },
            {
              "$ref": "#/definitions/fileSchema"
            }
          ]

but fileSchema is not included in the schema for parameter with in: body:

    "bodyParameter": {
      "type": "object",
      "required": [
        "name",
        "in",
        "schema"
      ],
      "patternProperties": {
        "^x-": {
          "$ref": "#/definitions/vendorExtension"
        }
      },
      "properties": {
        "description": {
          "type": "string",
          "description": "A brief description of the parameter. This could contain examples of use.  GitHub Flavored Markdown is allowed."
        },
        "name": {
          "type": "string",
          "description": "The name of the parameter."
        },
        "in": {
          "type": "string",
          "description": "Determines the location of the parameter.",
          "enum": [
            "body"
          ]
        },
        "required": {
          "type": "boolean",
          "description": "Determines whether or not this parameter is required or optional.",
          "default": false
        },
        "schema": {
          "$ref": "#/definitions/schema"
        }
      },

Thus, the following OpenAPI document does not pass schema validation.

swagger: "2.0"
info:
  title: Issue 1226
  description: 'type: file not allowed for body parameter '
  version: "1"
basePath: /issue-1126
paths:
  /issues:
    post:
      summary: Create a resource from the body
      consumes:
      - application/zip
      produces:
      - application/zip
      parameters:
      - name: content
        in: body
        required: true
        description: A zip file of the contents.
        schema:
          type: file
      responses:
        201:
          description:  Created.
          schema:
            type: file
          headers:
            Location:
              description: location of the new resource
              type: string

Source

DavidBiesack

Most helpful comment

Found a temporary workaround from https://github.com/OAI/OpenAPI-Specification/issues/326

schema:
  type: string
  format: binary

However, the code generation would produce byte[] instead of nicer Stream class.

jemerald on 21 Jul 2017

👍2

All 7 comments

Related: #254

Fak3 on 4 Jul 2017

@DavidBiesack type: file is not allowed in OpenAPI V3 for this reason

darrelmiller on 7 Jul 2017

Having the same trouble. Our API want to accept a single file of type application/pdf without using multipart/form-data. It is ideal as the GET and the PUT API lines up.

Example endpoint:

paths:
  /file:
    get:
      produces:
        - application/pdf
      responses:
        200:
          description: Successful response
          schema: 
            type: file
    put:
      consumes:
        - application/pdf
      parameters:
        - in: body
          name: file
          description: File to be uploaded
          required: true
          schema:
            type: file
      responses:
        200:
          description: Successful response

The GET method part is OK, but the PUT section errors in the editor