Swagger UI - Rendering nested object in multipart/form-data request "try it out" shows JSON instead of form UI fields

I am using Swagger/OpenAPI version: OpenAPI 3.0.3

Example Swagger/OpenAPI definition:

openapi: 3.0.3
info:
    title: 'My API'
    version: 3.0.0
servers: []
paths:
    /api_app:
        post:
            operationId: apiAppCreate
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            $ref: '#/components/schemas/ApiAppCreateRequest'
            responses:
                '200':
                    description: 'success'
                    content:
                        application/json:
                            schema: {}
components:
    schemas:
        ApiAppCreateRequest:
            properties:
                oauth:
                  type: object
                  properties:
                      callback_url:
                          type: string
                          example: 'https://example.com/oauth'
                      scopes:
                          type: array
                          items:
                              type: string
                          example:
                              - basic_account_info
                              - request_signature
            type: object

The nested object displays as Json input instead of form-data as shown in attached image.

It should be rendered as form-fields. This happens only when we have form-data or multipart/form-data type of request and it has a nested object within.

Seems no solution on github issues of swagger ui so thought of asking on stackoverflow if in case anyone able to resolve this issue.

I am using Java 8 with dependency:

<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

Another example of how the UI renders partly in form-data and partly as json input

Problem

I'm not sure what exactly oauth is being used as, but it seems like this is a request for an oauth token. The issue you are facing is due to your schema declaration, where you are declaring everything as a property of oauth. The type: object forces everything into a json schema, and by declaring everything as a property of oauth, it's forcing it into the oauth schema as a json object.

properties:
  oauth:
    type: object
    properties:

You can fix this two ways.

Solution 1

remove the top level properties value and reduce the indentation of the callback_url and scopes.

components:
  schemas:
    ApiAppCreateRequest:
      properties:
        oath:
          type: object
        callback_url:
          type: string
          example: 'https://example.com/oauth'
        scopes:
          type: array
          items:
            type: string
          example:
            - basic_account_info
            - request_signature
      type: object

This will result in the following display in your try it out

Solution 2

Remove the oauth entirely.

components:
  schemas:
    ApiAppCreateRequest:
      properties:
        callback_url:
          type: string
          example: 'https://example.com/oauth'
        scopes:
          type: array
          items:
            type: string
          example:
            - basic_account_info
            - request_signature
      type: object

This will remove the json object for oauth completely, as the below screenshot demonstrates.

Alternatives

Depending on what you are trying to do with the oauth property, you could also restructure what the property is, such as a file or a security schema:

As a file

As a file, simply update the schema to have a type: string and format: binary. This will allow the user to upload a file to be used as the security authorization.

oauth:
  type: string
  format: binary

As security schema

You can also include the oauth as the security schema separately as a part of the request.

openapi: 3.0.3
info:
    title: 'My API'
    version: 3.0.0
servers: []
paths:
  /api_app:
    post:
      operationId: apiAppCreate
      requestBody:
          content:
            multipart/form-data:
              schema:
                  $ref: '#/components/schemas/ApiAppCreateRequest'
      security:
        - oAuthSample:
          - create_app
      responses:
        '200':
          description: 'success'
          content:
            application/json:
              schema: {}
components:
  schemas:
    ApiAppCreateRequest:
      properties:
        callback_url:
          type: string
          example: 'https://example.com/oauth'
        scopes:
          type: array
          items:
            type: string
          example:
            - basic_account_info
            - request_signature
      type: object
  securitySchemes:
    oAuthSample:
      type: oauth2
      description: This API uses OAuth 2 with the implicit grant flow. [More info](https://whatever.com)
      flows:
        implicit:
          authorizationUrl: https://whatever.com
          scopes:
            create_app: create a new app

Finally

The multipart/form-data content type has a lot of possibilities. You can check the swagger documentation or the openapi documentation for more information. For example, you can use the encoding property to gain control over the way in which various parts of the request bodies are serialized. This includes setting the headers, explode, and style.