Problem

In OpenAPI 3.1 / JSON Schema 2020-12 a $ref may carry sibling keywords such as description, and their ordering is not significant. When a property combines $ref + description, schema generation breaks and produces a field with an empty type (or fails).

Root cause

ApiTool.hasRef only treated a node as a reference when $ref was the first field:

return (hasNode(schema, "$ref") || schema.fieldNames().hasNext()) && schema.fieldNames().next().equals("$ref");

If description appears before $ref (the usual ordering), hasRef returns false, the node falls through to the isBasicType branch and a field with an empty type is generated.

Changes

• hasRef now detects a top-level $ref regardless of field ordering.
• New regression test testRefWithDescription covering both orderings (description before and after $ref), with its assets.
• Version bump 6.4.1 → 6.4.2 (engine, maven-plugin, gradle-plugin).

Verification

multiapi-engine OpenAPI generator suite: 51/51 passing on top of main (mvn test -Dtest=OpenApiGeneratorTest#processFileSpec).

Example that reproduces the bug

Order:
  type: object
  properties:
    customer:
      description: The customer that placed the order
      $ref: "#/components/schemas/Customer"

🤖 Generated with Claude Code