Comment poster des fichiers dans Swagger (OpenAPI) ?

Question

J'utilise Swagger pour documenter mes services REST. L'un de mes services nécessite le téléchargement d'un fichier CSV. J'ai ajouté ce qui suit au fichier parameters dans ma définition de l'API JSON :

{
       "name": "File",
       "description": "The file in zip format.",
       "paramType": "body",
       "required": true,
       "allowMultiple": false,
       "dataType": "file"
}

et je vois maintenant l'option de téléchargement de fichier sur ma page Swagger UI. Mais lorsque je sélectionne un fichier et que je clique sur "try it out", j'obtiens l'erreur suivante :

NS_ERROR_XPC_BAD_OP_ON_WN_PROTO : Opération illégale sur un objet prototype WrappedNative dans jquery-1.8.0.min.js (ligne 2)

La page est traitée en continu et je n'obtiens aucune réponse.

Une idée de ce qui pourrait se passer ?

Answer 1

Spécification OpenAPI 2.0

Dans Swagger 2.0 ( Spécification OpenAPI 2.0 ), utiliser un paramètre de formulaire ( in: formData ) avec le type fixé à fichier . En outre, l'opération consumes doit être multipart/form-data .

  consumes:
    - multipart/form-data
  parameters:
    - name: file
      in: formData   # <-----
      description: The uploaded file data
      required: true
      type: file     # <-----

Spécification OpenAPI 3.0

En Spécification OpenAPI 3.0 Les fichiers sont définis comme des chaînes binaires, type: string + format: binary (ou format: byte en fonction du cas d'utilisation). Le contenu des entrées/sorties de fichiers est décrit avec la même sémantique que tout autre type de schéma (contrairement à OpenAPI 2.0) :

Demande en plusieurs parties, fichier unique :

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          # 'file' will be the field name in this multipart request
          file:
            type: string
            format: binary

Demande en plusieurs parties, tableau de fichiers (supporté dans Swagger UI 3.26.0+ et Swagger Editor 3.10.0+) :

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          # The property name 'file' will be used for all files.
          file:
            type: array
            items:
              type: string
              format: binary

POST/PUT directement (le corps de la requête est le contenu du fichier) :

requestBody:
  content:
    application/octet-stream:
      # any media type is accepted, functionally equivalent to `*/*`
      schema:
        # a binary file of any type
        type: string
        format: binary

Note : la sémantique est la même que pour les autres types de schémas OpenAPI 3.0 :

# content transferred in binary (octet-stream):
schema:
  type: string
  format: binary

Pour plus d'informations :

• Considérations relatives aux téléchargements de fichiers
• Considérations particulières pour le contenu multipartite
• Téléchargement de fichiers y Demandes multipartites

Answer 2

J'ai enfin trouvé la réponse à cette question. En fait, il n'y avait pas de support pour les téléchargement de fichiers Ils ont maintenant mis à jour swagger-ui.js fichier. Vous devez remplacer l'ancien fichier par le nouveau et définir ces propriétés sous Parameters pour un paramètre particulier :

 "paramType": "body",
 "dataType": "file",

Answer 3

Le mien semble fonctionner avec

 "paramType": "formData",
 "dataType": "file",

Answer 4

J'utilise Open API v 3.0.3

Voici à quoi ressemble mon swagger.json :

"/media/upload": {
      "post": {
        "tags": ["Media"],
        "name": "Upload Media",
        "description": "Uploads a Media file to the server.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "media": {
                    "type": "string",
                    "format": "base64"
                  }
                }
              }
            }
          }
        }
      }
    }

Voici comment il apparaît dans swagger :