Issue with OpenAPI 2.0

[michelealbano]

Description

Issue with Python and Ada, when using a Specification OpenAPI 2.0. Potentially, with the rest of the generators. The generator does not produce all the object classes used in the compiler.

openapi-generator version

Current master (3.0.1, I think)

OpenAPI declaration file content or url

swagger: '2.0'
info:
  version: 1.0.0
host: 127.0.0.1:8442
basePath: "/queryService"
consumes:
  - application/json
produces:
  - application/json


paths: 
  /query:
    put:
      operationId: query
      consumes:
        - multipart/form-data
      parameters:
        - name: serviceQueryForm
          in: body
          schema:
            $ref: '#/definitions/stringsMap'
      responses:
        default:
          description: Unexpected error

definitions: 
  stringsMap:
    type: "object"
    properties:
      entry:
        type: array
        items:
          type: object
          properties:
            key:
              type: string
            value:
              type: string

Command line used for generation

java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -o ../openapi2BAD/ -i ../openapi2problem.yml --model-package Arrowhead2 --additional-properties projectName=Arrowhead1 -g python 

or

java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate -o ../openapi2BAD/ -i ../openapi2problem.yml --model-package Arrowhead2 --additional-properties projectName=Arrowhead1 -g python 

Steps to reproduce

cd openapi2BAD/ && mkdir bin && gprbuild -P arrowhead1.gpr

Related issues/PRs

Suggest a fix/enhancement

[wing328]

      consumes:
        - multipart/form-data
      parameters:
        - name: serviceQueryForm
          in: body
          schema:
            $ref: '#/definitions/stringsMap'

Should form parameters (in: formData) be used instead?

[jmini]

@wing328: I think the object is filtered from the list of "models to generate" with ModelUtils.getSchemasUsedOnlyInFormParam(OpenAPI) (see #74).

[wing328]

@jmini my point is whether the spec (2.0) is correctly describing the API (independent of which code generator is processing the spec)

[jimschubert]

In OpenAPI 2.0, application/x-www-form-urlencoded and multipart/form-data should be in formData as William said above see spec.

The spec doesn't make this as clear as it could (and should), so I'll quote the relevant parts:

Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4)

and just below this in the spec:

multipart/form-data - each parameter takes a section in the payload with an internal header. For example, for the header Content-Disposition: form-data; name="submit-name" the name of the parameter is submit-name. This type of form parameters is more commonly used for file transfers.

And if you follow the link in the spec to the forms spec:

The content type "application/x-www-form-urlencoded" is inefficient for sending large quantities of binary data or text containing non-ASCII characters. The content type "multipart/form-data" should be used for submitting forms that contain files, non-ASCII data, and binary data.

This may not seem entirely clear still, so consider how the parser parses body versus formData. A body schema is basically deconstructed into whatever single model you have defined for that body. On the other hand, multipart/form-data has multiple parts to be parsed. From the forms spec:

   Content-Type: multipart/form-data; boundary=AaB03x

   --AaB03x
   Content-Disposition: form-data; name="submit-name"

   Larry
   --AaB03x
   Content-Disposition: form-data; name="files"
   Content-Type: multipart/mixed; boundary=BbC04y

   --BbC04y
   Content-Disposition: file; filename="file1.txt"
   Content-Type: text/plain

   ... contents of file1.txt ...
   --BbC04y
   Content-Disposition: file; filename="file2.gif"
   Content-Type: image/gif
   Content-Transfer-Encoding: binary

   ...contents of file2.gif...
   --BbC04y--
   --AaB03x--

The parser doesn't parse contents like the above into a single body model instance. I don't know that it really code (how would you differentiate the property names of a single model for the two files in the above example?).

In OpenAPI 3.x confusion around multipart/form-data is mostly removed in my opinion, although the defaults for content types as defined in the spec make me a little cautious as I prefer explicit declarations to implicit type mappings.

I hope this helps provide a little clarity to the comments above about in: formData. Please retry with that small change and see if this resolves the issue.

@wing328 I know this parsing is done by the parser and not by openapi-generator, but do you think it would be helpful to look into the effort it would take to add a warning if you have one of application/x-www-form-urlencoded or multipart/form-data in the same schema with an in: body?

[neclimdul]

It sounds like from the description that the whole FormData discussion is not really relevant. Removing it still causes the object to not be created which i'm pretty sure @jmini identified why. If you're converting from swagger's codegen that can really break your API library. That aside I think its creating some legit bugs from code that isn't ready to handle that.

If you for example want a simplified inline json object(maybe without ID or something that doesn't exist yet) for your create method you might create an API like this:

swagger: '2.0'
info:
  version: 1.0.0
consumes:
  - application/json
produces:
  - application/json

paths:
  /person:
    post:
      operationId: createPerson
      parameters:
        - name: MyObject
          in: body
          schema:
            type: object
            properties:
              email:
                type: string
                format: email
              enabled:
                type: boolean
      responses:
        default:
          description: Unexpected error

which generates the following warning:

[main] WARN org.openapitools.codegen.DefaultCodegen - The folowing schema has undefined (null) baseType. It could be due to form parameter defined in OpenAPI v2 spec with incorrect consumes. A correct 'consumes' for form parameters should be 'application/x-www-form-urlencoded' or 'multipart/form-data'
[main] WARN org.openapitools.codegen.DefaultCodegen - schema: class ObjectSchema {
    class Schema {
        title: null
        multipleOf: null
        maximum: null
        exclusiveMaximum: null
        minimum: null
        exclusiveMinimum: null
        maxLength: null
        minLength: null
        pattern: null
        maxItems: null
        minItems: null
        uniqueItems: null
        maxProperties: null
        minProperties: null
        required: null
        type: null
        not: null
        properties: {email=class EmailSchema {
            class Schema {
                title: null
                multipleOf: null
                maximum: null
                exclusiveMaximum: null
                minimum: null
                exclusiveMinimum: null
                maxLength: null
                minLength: null
                pattern: null
                maxItems: null
                minItems: null
                uniqueItems: null
                maxProperties: null
                minProperties: null
                required: null
                type: null
                not: null
                properties: null
                additionalProperties: null
                description: null
                format: null
                $ref: null
                nullable: null
                readOnly: null
                writeOnly: null
                example: null
                externalDocs: null
                deprecated: null
                discriminator: null
                xml: null
            }
            type: string
            format: email
            _default: null
            _enum: null
        }, enabled=class BooleanSchema {
            class Schema {
                title: null
                multipleOf: null
                maximum: null
                exclusiveMaximum: null
                minimum: null
                exclusiveMinimum: null
                maxLength: null
                minLength: null
                pattern: null
                maxItems: null
                minItems: null
                uniqueItems: null
                maxProperties: null
                minProperties: null
                required: null
                type: null
                not: null
                properties: null
                additionalProperties: null
                description: null
                format: null
                $ref: null
                nullable: null
                readOnly: null
                writeOnly: null
                example: null
                externalDocs: null
                deprecated: null
                discriminator: null
                xml: null
            }
            type: boolean
            _default: null
            _enum: null
        }}
        additionalProperties: null
        description: null
        format: null
        $ref: null
        nullable: null
        readOnly: null
        writeOnly: null
        example: null
        externalDocs: null
        deprecated: null
        discriminator: null
        xml: null
    }
    type: object
    defaultObject: null
}
[main] WARN org.openapitools.codegen.DefaultCodegen - Defaulting baseType to UNKNOWN_BASE_TYPE

And then some wonky code like the following php:

    /**
     * Operation createPerson
     *
     * @param  object $unknown_base_type unknown_base_type (optional)
     *
     * @throws \...\ApiException on non-2xx response
     * @throws \InvalidArgumentException
     * @return void
     */
    public function createPerson($unknown_base_type = null)
    {
        $this->createPersonWithHttpInfo($unknown_base_type);
    }