Saya mencoba menggunakan Swagger untuk menentukan API yang menerima file aktual dan objek skema yang mendeskripsikan konten file. Berikut ini cuplikan dari Swagger YAML. Namun itu tidak akan memvalidasi di Editor Swagger.
/document:
post:
summary: Api Summary
description: Api Description
consumes:
- multipart/form-data
parameters:
- name: documentDetails
in: formData
description: Document Details
required: true
schema:
$ref: '#/definitions/Document'
- name: document
in: formData
description: The actual document
required: true
type: file
Editor Swagger melemparkan kesalahan validasi berikut:
Kesalahan Swagger: Data tidak cocok dengan skema apa pun dari 'oneOf'
Apakah saya kehilangan sesuatu? Atau Apakah ini bukan fitur yang didukung dari Swagger?
kesombongan tidak mendukung tipe 'objek' dalam bentukData, hanya sebagai parameter tubuh.
Ini mungkin dalam OpenAPI 3.0, tetapi tidak di OpenAPI / Swagger 2.0.
OpenAPI / Swagger 2.0 tidak mendukung objek dalam bentuk data. Parameter bentuk dapat berupa nilai primitif, larik primitif, dan file, tetapi bukan objek. Jadi contoh Anda tidak dapat dijelaskan menggunakan OpenAPI 2.0.
Di OpenAPI 3.0, Anda dapat menggunakan:
paths:
/document:
post:
summary: Api Summary
description: Api Description
requestBody:
required: true
content:
multipart/form-data:
# Form parameters from 2.0 become body schema properties in 3.0
schema:
type: object
properties:
# Schema properties correspond to individual parts
# of the multipart request
document:
# In 3.0, files are binary strings
type: string
format: binary
description: The actual document
documentDetails:
$ref: '#/components/schemas/Document'
# The default Content-Type for objects is `application/json`
required:
- document
- documentDetails
Bagian yang relevan dari 3.0 Spesifikasi:
Pertimbangan untuk Unggahan File
Pertimbangan Khusus untuk Konten Multipart
Tidak mungkin menggunakan Swagger 2.0, Anda hanya bisa membacanya sebagai 'file' tipe,
https://swagger.io/docs/specification/2-0/file-upload/
Pada catatan terkait harap diperhatikan bahwa mengunggah susunan file juga tidak didukung di Swagger 2.0 tetapi didukung di Open API 3.0.
https://github.com/OAI/OpenAPI-Specification/issues/254