OpenAPI3多部分请求在Swagger及Azure APIM中不展示Schema与示例

我在编写API的OpenAPI规范时发现，Swagger编辑器（editor.swagger.com）和Azure API Management自动生成的开发者门户，都无法展示multipart/form-data请求中JSON对象的详情。没有解析错误，但原本期望这个JSON对象能像其他请求类型一样显示示例/Schema选择器，方便开发者查看对象结构。我尝试给多部分请求关联的FileUploadData Schema添加示例值，但没有任何变化。想知道有没有办法强制显示这些详情并调出Schema按钮，或者是不是多数OpenAPI查看器都不支持这个功能？

原OpenAPI规范代码 #

openapi: 3.0.1
info:
  title: SFTP Functions
  description: Import from "test-functionapp" Function App
  version: '1.0'
servers:
  - url: example.com
paths:
  /uploadfile:
    post:
      summary: UploadFile
      description: UploadFile
      operationId: post-uploadfile
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                sftpdata:
                  $ref: '#/components/schemas/FileUploadData'
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: The file was uploaded successfully.
components:
  schemas:
    FileUploadData:
      type: object
      properties:
        Url:
          type: string
        Username:
          type: string
        Password:
          type: string
        Port:
          type: string
        Path:
          type: string
      example:
        Url: "hello"
        Username: "test"
        Password: "password"
        Port: "2022"
        Path: "/"

目前主流OpenAPI可视化工具（包括Swagger Editor、Azure APIM开发者门户）对multipart/form-data嵌套JSON对象的展示支持确实有限，不过可以通过以下两种方式优化展示效果：

方式1：为JSON字段显式指定媒体类型 #

修改multipart/form-data的Schema定义，给sftpdata字段添加contentType: application/json，让工具识别出这是一个JSON类型的表单字段，从而展示其Schema结构和示例：

openapi: 3.0.1
info:
  title: SFTP Functions
  description: Import from "test-functionapp" Function App
  version: '1.0'
servers:
  - url: example.com
paths:
  /uploadfile:
    post:
      summary: UploadFile
      description: UploadFile
      operationId: post-uploadfile
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                sftpdata:
                  $ref: '#/components/schemas/FileUploadData'
                  contentType: application/json # 新增媒体类型指定
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: The file was uploaded successfully.
components:
  schemas:
    FileUploadData:
      type: object
      properties:
        Url:
          type: string
        Username:
          type: string
        Password:
          type: string
        Port:
          type: string
        Path:
          type: string
      example:
        Url: "hello"
        Username: "test"
        Password: "password"
        Port: "2022"
        Path: "/"

方式2：使用encoding字段定义 #

通过OpenAPI的encoding特性，为sftpdata字段指定媒体类型，明确告知工具该字段的格式：

openapi: 3.0.1
info:
  title: SFTP Functions
  description: Import from "test-functionapp" Function App
  version: '1.0'
servers:
  - url: example.com
paths:
  /uploadfile:
    post:
      summary: UploadFile
      description: UploadFile
      operationId: post-uploadfile
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                sftpdata:
                  $ref: '#/components/schemas/FileUploadData'
                file:
                  type: string
                  format: binary
            encoding: # 新增encoding配置
              sftpdata:
                contentType: application/json
      responses:
        '200':
          description: The file was uploaded successfully.
components:
  schemas:
    FileUploadData:
      type: object
      properties:
        Url:
          type: string
        Username:
          type: string
        Password:
          type: string
        Port:
          type: string
        Path:
          type: string
      example:
        Url: "hello"
        Username: "test"
        Password: "password"
        Port: "2022"
        Path: "/"

补充说明 #

• 两种方式都能让Swagger Editor和Azure APIM开发者门户识别出sftpdata的JSON结构，进而展示Schema选择器和示例值。
• 并非所有OpenAPI查看器都支持该特性，但Swagger UI、Redoc等主流工具在添加配置后均可正常展示。

内容的提问来源于stack exchange，提问作者Caleb Keller