Display schema for mutipart/form-data object properties

[AlexisAmd]

Content & configuration

Swagger/OpenAPI definition:

openapi: 3.0.3
info:
 title: Example app
 description: This is an example
 version: 1.0.0
servers:
 - url: https://dev.app.com/appApplicationName
   description: DEV
paths:
 /documents:
   post:
     description: >
       The structure of the *metadata* property should conform to the schema
       defined in the
       [ModelPostDocumentInvoice](#/components/schemas/ModelPostDocumentInvoice)
       schema outlined at the bottom of this page. summary: Multipart/form-data
       with json object property + file
     requestBody:
       content:
         multipart/form-data:
           schema:
             $ref: '#/components/schemas/ModelPostDocumentInvoiceCombineModelFile'
     operationId: test2
     responses:
       '200':
         description: ok
         content:
           application/json:
             schema:
               type: string
               description: ok
components:
 schemas:
   ModelFile:
     type: object
     properties:
       file:
         type: string
         format: binary
     required:
       - file
   AbstractModelPostDocument:
     type: object
     properties:
       title:
         type: string
         default: ''
         maxLength: 64
         example: MyDocument.pdf'
         description: Displayed title. Can be different than filename
       category:
         type: string
         enum:
           - Invoice
           - Receipt
           - Credit note
           - Purchase Order
       documentDate:
         type: string
         description: >-
           Creation date of the document. Example : For ID card, it is the
           issuing date of the card.
         format: date
     required:
       - title
       - category
       - documentDate
   ModelPostDocumentInvoice:
     allOf:
       - $ref: '#/components/schemas/AbstractModelPostDocument'
       - type: object
         properties:
           amount:
             type: number
             example: 1234.56
             description: Invoice Amount
         description: Metadata for invoice documents
         required:
           - amount
   ModelPostDocumentOneOf:
     oneOf:
       - $ref: '#/components/schemas/ModelPostDocumentInvoice'
   ModelPostDocumentInvoiceCombineModelFile:
     allOf:
       - $ref: '#/components/schemas/ModelFile'
       - type: object
         properties:
           metadata:
             $ref: '#/components/schemas/ModelPostDocumentInvoice'
         description: metadata
         required:
           - metadata
   ModelPostDocumentOneOfCombineModelFile:
     allOf:
       - $ref: '#/components/schemas/ModelFile'
       - type: object
         properties:
           metadata:
             $ref: '#/components/schemas/ModelPostDocumentOneOf'
         required:
           - metadata

Is your feature request related to a problem?

In the example provided the 'metadata' which is an object property property is defined using a schema.
After clicking on 'Try it out' an example based on this schema is displayed, however the schema is not displayed in Swagger UI.

Consequently :

• As API provider I have to provide a link in description to inform consummer that the json for the property should follow the schema
  

• As API consumer I have to scroll down to the bottom of the OAS definition to display the schema.
  

Describe the solution you'd like

With the impovement, for each obect property, the user is allowed to choose between 'Example value' and 'Schema'

Describe alternatives you've considered

Current solution : Add link to the schema in endpoint's description

Additional context

The purpose of this endpoint is to offer a versatile method for uploading files and associated metadata of various types. The set of metadata required depends on the nature of the file, such as Invoicing or Identification documents (see Schemas for examples).

Related issues :

• Display static documentation information for multipart properties in OpenAPI 3.0 files #5169
  -> Is asking to show a preview of the payload (an example) without clicking on "Try it out"
• Display the Model/schema for object and array[object] parameters #4581
  -> Is asking the same as this one but for query parameters
• Schema not rendered for query parameter #7696
  -> Same as 4581

[kenchen-cs]

As it's not officially supported, I have to do it myself. My solution is simple and just show the example value like clicking "Try it out". Even though it's not as fancy as your example, it's better than nothing.

kenspirit@d325fd8

[jearton]

Need it + 1

[kenspirit]

As it's not officially supported, I have to do it myself. My solution is simple and just show the example value like clicking "Try it out". Even though it's not as fancy as your example, it's better than nothing.

kenspirit@d325fd8

The change can be checked for a better handling now in: https://github.com/kenspirit/swagger-ui/tree/multipart-body-show-schema

[iliaszh]

same problem here

[glowcloud]

Hi all,

This issue was addressed at some point, as in the latest Swagger UI version, both the example and schema are displayed when clicking on Try it out:

There is still a separate enhancement possible – displaying them without Try it out. This can be tracked in #5169.