[BUG] [html2][html][dynamic-html] using allOf/oneOf in request body generates broken documentation

[hauntingEcho]

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator (example)?
• Have you tested with the latest master to confirm the issue still exists?
• Have you searched for related issues/PRs?
• What's the actual output vs expected output?
• [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

Using allOf or oneOf in a request body produces broken documentation. In the example below, it documents a body parameter of 'uNKNOWNBASETYPE' with a type of 'undefined'.

The following will be produced in the log:

[main] INFO  o.o.codegen.DefaultGenerator - Generating with dryRun=false
[main] INFO  o.o.codegen.DefaultGenerator - OpenAPI Generator: html2 (documentation)
[main] INFO  o.o.codegen.DefaultGenerator - Generator 'html2' is considered stable.
[main] INFO  o.o.codegen.utils.URLPathUtils - 'host' (OAS 2.0) or 'servers' (OAS 3.0) not defined in the spec. Default to [http://localhost] for server URL [http://localhost/]
[main] INFO  o.o.codegen.utils.URLPathUtils - 'host' (OAS 2.0) or 'servers' (OAS 3.0) not defined in the spec. Default to [http://localhost] for server URL [http://localhost/]
[main] WARN  o.o.codegen.DefaultCodegen - Empty operationId found for path: patch /pets. Renamed to auto-generated operationId: petsPatch
[main] WARN  o.o.codegen.DefaultCodegen - The following 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 'app
lication/x-www-form-urlencoded' or 'multipart/?'
[main] WARN  o.o.codegen.DefaultCodegen - schema: class ComposedSchema {
    class Schema {
        type: null
        format: null
        $ref: null
        description: null
        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
        not: null
        properties: null
        additionalProperties: null
        nullable: null
        readOnly: null
        writeOnly: null
        example: null
        externalDocs: null
        deprecated: null
        discriminator: null
        xml: null
    }
    allOf: null
    anyOf: null
    oneOf: [class ObjectSchema {
        class Schema {
            type: object
            format: null
            $ref: null
            description: null
            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
            not: null
            properties: {bark=class BooleanSchema {
                class Schema {
                    type: boolean
                    format: null
                    $ref: null
                    description: null
                    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
                    not: null
                    properties: null
                    additionalProperties: null
                    nullable: null
                    readOnly: null
                    writeOnly: null
                    example: null
                    externalDocs: null
                    deprecated: null
                    discriminator: null
                    xml: null
                }
            }}
            additionalProperties: null
            nullable: null
            readOnly: null
            writeOnly: null
            example: null
            externalDocs: null
            deprecated: null
            discriminator: null
            xml: null
        }
    }]
}
[main] WARN  o.o.codegen.DefaultCodegen - codegenModel is null. Default to UNKNOWN_BASE_TYPE
[main] INFO  o.o.codegen.utils.URLPathUtils - 'host' (OAS 2.0) or 'servers' (OAS 3.0) not defined in the spec. Default to [http://localhost] for server URL [http://localhost/]
[main] INFO  o.o.codegen.utils.URLPathUtils - 'host' (OAS 2.0) or 'servers' (OAS 3.0) not defined in the spec. Default to [http://localhost] for server URL [http://localhost/]
[main] INFO  o.o.codegen.TemplateManager - writing file /local/out/index.html
[main] INFO  o.o.codegen.TemplateManager - Skipped /local/out/.openapi-generator-ignore (Skipped by supportingFiles options supplied by user.)
[main] INFO  o.o.codegen.TemplateManager - writing file /local/out/.openapi-generator/VERSION
[main] INFO  o.o.codegen.TemplateManager - writing file /local/out/.openapi-generator/FILES
################################################################################
# Thanks for using OpenAPI Generator.                                          #
# Please consider donation to help us maintain this project 🙏                 #
# https://opencollective.com/openapi_generator/donate                          #
[main] INFO  o.o.codegen.TemplateManager - writing file /local/out/.openapi-generator/VERSION
[main] INFO  o.o.codegen.TemplateManager - writing file /local/out/.openapi-generator/FILES
################################################################################
# Thanks for using OpenAPI Generator.                                          #
# Please consider donation to help us maintain this project 🙏                 #
# https://opencollective.com/openapi_generator/donate                          #
################################################################################

openapi-generator version

5.3.0

OpenAPI declaration file content or url

This is a stripped-down version of the first oneOf example here. Using allOf instead produces the same error.

openapi: 3.0.3
info:
  title: test
  description: test
  version: 0.0.1
paths:
  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    bark:
                      type: boolean
      responses:
        '200':
          description: Updated

allOf seems to work only if the internal type is not a reference. The following will break it:

openapi: 3.0.3
info:
  title: test
  description: test
  version: 0.0.1
paths:
  /pets:
    patch:
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/Dog'
      responses:
        '200':
          description: Updated
components:
  schemas:
    Dog:
      type: object
      properties:
        bark:
          type: boolean

Generation Details / Steps to reproduce

1. start on Windows, having installed git-bash and docker
2. Add the above YAML to test.yml
3. MSYS_NO_PATHCONV=1 docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli:v5.3.0 generate --input-spec "/local/test.yml" --output "/local/out" --generator-name html2
4. open out/index.html

Related issues/PRs

• [BUG] [csharp-netcore] UNKNOWN BASE TYPE when using allOf in request body schema declaration #7339
• [BUG][PYTHON] Using Openapi 3.0 Inheritance/Polymorphism keywords (allOf, anyOf, oneOf) causes generation of UNKNOWNBASETYPE model. #8892
• [BUG] [JAVA] UNKNOWN BASE TYPE when using allOf in request body schema declaration #2892
• [BUG][java] oneOf in "anonymous" schemas: model not generated. #5903
• [BUG] [csharp-netcore] When requestBody has OneOf, then it generates client with "UNKNOWN_BASE_TYPE" #9788
• [BUG] Inheritance is broken #2845
• [REQ][Bounty] AnyOf - OneOf - AllOf support #10514

[hauntingEcho]

From chasing this around some, it looks like definitions are being put into the 'definitions' property (used by Swagger v2) rather than 'components' (used by OpenAPI v3) here: https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/main/resources/htmlDocs2/paramB.mustache#L15

[marianhlavac]

I have the same issue when using FastAPI to generate automatic OpenAPI. Following output gives the same error.

        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "title": "Status",
                "allOf": [{ "$ref": "#/components/schemas/DeviceStatus" }],
                "description": "Device status with updated values"
              }
            }
          },
          "required": true
        },

According to this issue fastapi/fastapi#684 this has been already investigated by the author of the library and it seems that the OpenAPI document is according to the spec:

It's part of the OpenAPI spec. When using $ref, the object containing it cannot contain any additional properties. So the only way to have a $ref and a description is through allOf.

This object cannot be extended with additional properties and any properties added SHALL be ignored.
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#fixed-fields-19

It seems like there is, indeed, a bug in the generator.

[wing328]

Should be fixed by #12353. Please pull the latest master to give it another try.