Display schema for mutipart/form-data object properties

AlexisAmd commented 4 months ago

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 :

5169

-> Is asking to show a preview of the payload (an example) without clicking on "Try it out"
4581

-> Is asking the same as this one but for query parameters
7696

-> Same as 4581

kenchen-cs commented 2 months ago

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.

https://github.com/kenspirit/swagger-ui/commit/d325fd8392c9a10000699204f9619fb27990df78

jearton commented 1 month ago

Need it + 1

kenspirit commented 1 month ago

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

swagger-api / swagger-ui