如何使用OpenAPI3在多部分/表单数据请求的请求体中格式化JSON数组？ [英] How to format a JSON array in the request body of a multipart/form-data request with OpenAPI 3?

问题描述

我正在尝试为现有终结点编写OpenAPI3规范。终结点使用Content-Typeofmultipart/form-data，其中一个参数接受JSON数组字符串。下面的卷曲显示了此终结点正常工作的示例：

curl -X 'POST' 
  'https://testing.org/test/' 
  -H 'accept: */*' 
  -H 'Content-Type: multipart/form-data' 
  -F 'simple=abc' 
  -F 'complex=[{"key": "string", "size": 0}"]'

我的OpenAPI 3规格目前如下所示：

openapi: 3.0.3
info:
  title: Simple
  description: Testing
  version: '1.0'
servers:
  - url: 'https://testing.org'
paths:
  /test/:
    post:
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                simple: 
                  type: string
                complex:
                  type: array
                  items:
                      type: object
                      properties:
                        key: 
                          type: string
                        size: 
                          type: integer
            encoding:
              complex:
                contentType: application/json
      responses:
        '200':
          description: OK

但是，在swagger editor中使用"；test out"；功能会产生如下所示的请求：

curl -X 'POST' 
  'https://testing.org/test/' 
  -H 'accept: */*' 
  -H 'Content-Type: multipart/form-data' 
  -F 'simple=abc' 
  -F 'complex=["{
  "key": "string",
  "size": 0
}"]'

complex参数格式不正确。如果我删除了规范的encoding部分，则请求如下所示：

curl -X 'POST' 
  'https://testing.org/test/' 
  -H 'accept: */*' 
  -H 'Content-Type: multipart/form-data' 
  -F 'simple=abc' 
  -F 'complex={
  "key": "string",
  "size": 0
}'

它是JSON对象，但不是JSON数组。

关于如何格式化OpenAPI 3规范，以便将complex表单参数格式化为简单的JSON数组[{"key": "string", "size": 0}"]，有什么建议吗？谢谢！

推荐答案

您的接口定义正确。它甚至应该在没有encoding的情况下工作，因为对象和对象数组的Content-Type默认情况下是application/json。

问题是Swagger UI和Swagger编辑器尚不能在多部分Body中正确支持JSON。以下是您可以跟踪的相关问题：

• Encoding attribute is not respected on the request
• Generated CURL seems wrong for mime/multipart uploads that have JSON parts - missing 'type=' option, wrong quotes
• multipart/form-data should support custom content-type selection

这篇关于如何使用OpenAPI3在多部分/表单数据请求的请求体中格式化JSON数组？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！