[BUG][openapi-yaml] Auto-generated object-level `example` has unstable field order due to non-ordered Map

[123yoshidandy]

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator?
• Have you tested with the latest master to confirm the issue still exists? (verified with v7.22.0)
• 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

Description

When the openapi-yaml generator processes an object schema whose properties each have an example, it auto-generates an object-level example: {...} by aggregating each property's example value. The field order inside this auto-generated example does not match the property declaration order from the source spec, and it is also not strictly alphabetical — the order appears to be unstable.

This affects downstream consumers such as Swagger UI, which renders the auto-generated example as-is in the "Example Value" panel, so users see fields in an order that differs from the spec. Not a critical bug, but it does reduce the readability of the rendered documentation.

I suspect the underlying cause may be a non-ordered HashMap (rather than something like LinkedHashMap) being used when aggregating the example map inside the generator. Apologies if this turns out to be incorrect — I have not been able to fully trace the generator source, only observed the symptom.

openapi-generator version

Reproduced with v7.22.0 (latest stable as of 2026-04). The issue has likely existed across many earlier versions.

OpenAPI declaration file content or url

Minimal reproducer (repro.yaml):

openapi: 3.0.0
info:
  title: Reproduce object-level example reordering
  version: 1.0.0
paths:
  /foo:
    get:
      operationId: getFoo
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Foo'
components:
  schemas:
    Foo:
      type: object
      required:
        - zebra
        - apple
        - mango
        - cherry
        - banana
      properties:
        zebra:
          type: integer
          example: 1
        apple:
          type: integer
          example: 2
        mango:
          type: integer
          example: 3
        cherry:
          type: integer
          example: 4
        banana:
          type: integer
          example: 5

Property declaration order is intentionally non-alphabetical (zebra, apple, mango, cherry, banana) to make the bug visible.

Generation Details

java -jar openapi-generator-cli-7.22.0.jar generate \
  -i repro.yaml \
  -g openapi-yaml \
  -o ./output

Steps to reproduce

1. Save the YAML above as repro.yaml.
2. Run the generation command above.
3. Inspect output/openapi/openapi.yaml, in particular the components.schemas.Foo section.

Actual output

components:
  schemas:
    Foo:
      example:
        zebra: 1
        banana: 5
        apple: 2
        cherry: 4
        mango: 3            # ← unstable, unpredictable order (HashMap-like)
      properties:
        zebra:
          example: 1
          type: integer
        apple:
          example: 2
          type: integer
        mango:
          example: 3
          type: integer
        cherry:
          example: 4
          type: integer
        banana:
          example: 5
          type: integer
      required:
      - apple
      - banana
      - cherry
      - mango
      - zebra
      type: object

Note that the auto-generated example field order is zebra, banana, apple, cherry, mango — neither matching the declaration order nor strictly alphabetical. The unstable nature of this order is what made me suspect a HashMap-style implementation underneath.

Expected output

The auto-generated example should preserve the order from the properties declaration:

example:
  zebra: 1
  apple: 2
  mango: 3
  cherry: 4
  banana: 5

The properties map itself already preserves declaration order in the output, so the same order should be used when constructing the aggregated example.

Related issues/PRs

• [BUG][openapi-yaml] Merged spec reorders HTTP operations under the same path, breaking intended method ordering #23009 — [BUG][openapi-yaml] Merged spec reorders HTTP operations under the same path. A related ordering bug in the same generator, but with a different root cause: that issue is caused by an explicit alphabetical sort (skipSortingOperations=false by default), whereas this example reordering is caused by an unordered Map. The two are distinct problems that likely require independent fixes.

Suggest a fix

If my suspicion is correct, one possible fix would be to use a LinkedHashMap (instead of a non-ordered Map) when constructing the aggregated object-level example, iterating over the source schema's properties in declaration order so that the resulting example mirrors the property order.

I traced the YAML serialization path partway:

• OpenAPIYamlGenerator.postProcessSupportingFileData calls DefaultCodegen.generateYAMLSpecFile
• which delegates to SerializerUtils.toYamlString(openAPI)
• SerializerUtils.toYamlString configures Jackson with MapperFeature.SORT_PROPERTIES_ALPHABETICALLY = true. However, this only sorts Bean fields, not the contents of Map<String, Object> values such as the body of Schema.example.

So the field reordering is unlikely to come from the serializer step itself. My guess is that the auto-generated object-level example is being constructed somewhere upstream — possibly in swagger-parser, OpenAPINormalizer, InlineModelResolver, or another resolver — using a non-ordered Map. I was not able to pin down the exact location, so any pointer from a maintainer familiar with the codebase would be very welcome.

For my own use case, I have already worked around this in my build pipeline by post-processing the generated YAML, so this issue is not blocking me. I am filing it primarily so other users encountering the same symptom can find a reference, and for the maintainers' awareness.

[swapneswarsundarray]

I can take a look at this. It seems like the object-level example is being built using an unordered Map. Planning to switch to LinkedHashMap and preserve property declaration order during aggregation. Let me know if that approach aligns.

[123yoshidandy]

Thanks @swapneswarsundarray for the fix, and to the maintainers for the quick review and merge. Much appreciated!