[ALL] Form params - individual or as container?

While writing my own code generator I noticed something weird: codegen would generate models called Body, Body1, ... that the generated code didn't use.

After some digging I found out that this is a result of the change of how form parameters are handled in OAS2 (Swagger) vs. OAS3 (OpenAPI),

In OAS2 form parameters were defined like this:

parameters:
  - in: formData
    name: name
    type: string
    description: A person's name.
  - in: formData
    name: fav_number
    type: number
    description: A person's favorite number.

The "natural" form for the generated api methods here is to have individual parameters (name, fav_number).

In OAS3 the form has changed to this:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          additionalMetadata:
            description: Additional data to pass to server
            type: string
          file:
            description: file to upload
            type: string
            format: binary

The "natural" form for this would be to pass all parameters as an object (as opposed to individual parameters).

In fact, if the content type is switched from multipart/form-data to application/json, all/most/some code generators will switch from individual parameters to container data types.

The problem with the redundant files I mentioned earlier stems from a design decision in the swagger parser: inline schemas are automatically "externalized", i.e. they're moved to the global components/schema section and replaced with a $ref. So, the example above basically becomes:

requestBody:
  content:
    multipart/form-data:
      schema:
        $ref: '#/components/schemas/body'

components:
  schemas:
    body:
      type: object
      properties:
        additionalMetadata:
          description: Additional data to pass to server
          type: string
        file:
          description: file to upload
          type: string
          format: binary

So, the code generators would see a model called body and thus generate a file for it - while the operations would use the formParams collection and create individual parameters.

The question now is: Which way will be the future?

The current implementation points to "container models" but this would be breaking change for existing api users. There are also two todos in the code that may suggest there is some plan for this. Unfortunately, they don't have an issue number so I'm not sure where their progress is tracked.

On the other hand we could stay with individual parameters but would then require a way to figure out whether a model file should be generated or not. (I'm currently trying this way but it's rather difficult because you need to find all schema usages in an OpenAPI instance - and there seems to be no straight forward way of doing this.)

Start with DefaultCodegenConfig.java, especially the formParams handling and its two TODOs, then review InlineModelResolver.java to understand why inline request schemas become generated models. Compare the OAS2 and OAS3 examples and existing generator behavior; done requires an agreed direction for individual form parameters versus container models, with the redundant-model behavior addressed consistently.