Report OpenAPI definitions the adapter cannot use

[glen-84]

Summary

• Definitions the adapter skips are no longer dropped in silence. Endpoints whose composed document fails validation against the schema, endpoints that cannot be prepared for execution, and definitions that cannot be described in the OpenAPI document all report through IOpenApiDiagnosticEventListener, naming the definition and the reason. The errors were already being computed and then discarded.
• Endpoints with an invalid document are excluded from the OpenAPI document. Most already were, because describing them failed anyway; this makes it consistent, so the specification no longer advertises an endpoint that returns HTTP 500 on every call.
• Two unguarded lookups in the document transformer threw KeyNotFoundException, whose message would now reach users verbatim. They throw a message naming the missing fragment or field instead.
• Document how to register a listener, including the AddApplicationService<ILogger<T>>() step that listener activation from the schema services requires.

Behaviour is otherwise unchanged: an endpoint that cannot execute is still routed and still returns HTTP 500, per the design in #9022.

Test plan

• Three new tests covering an endpoint that spreads an undefined fragment, one that spreads another model's private helper, and one that selects an unknown field; each asserts the exact reported message.
• Verified the reports actually fire by removing the emitting call and confirming the tests fail, then restoring it.
• Verified the documented listener registration end to end, including that it fails without AddApplicationService<ILogger<T>>().
• Full HotChocolate.Adapters.OpenApi.Tests suite on net9.0, net10.0, and net11.0: 238 passed, 2 skipped. No snapshot changed.
• prettier@3.8.3 --no-config --check on the changed docs page.

Reported in #10215. Not a full fix for that issue: making these ordinary validation errors, and failing at startup rather than routing an endpoint that returns HTTP 500, are design decisions still to be made.

[github-actions]

Patch coverage

80.0% of changed lines covered (52/65)

File	Covered	Changed	Patch %
…/src/Adapters.OpenApi.Core/OpenApiDefinitionRegistry.cs	20	27	74.1% 🔴
…/DynamicOpenApiDocumentTransformer.cs	28	34	82.4% 🟡
…/Adapters.OpenApi.Core/Execution/OpenApiEndpointDescriptor.cs	3	3	100.0% 🟢
…/Adapters.OpenApi.Core/Execution/OpenApiEndpointFactory.cs	1	1	100.0% 🟢

Uncovered changed lines (JSON)

{
  "sha": "3e8794e42b0e5e2e4c98be372f39ad0b1f86ce3f",
  "files": [
    { "path": "src/HotChocolate/Adapters/src/Adapters.OpenApi.Core/OpenApiDefinitionRegistry.cs", "ranges": [[203, 203], [205, 210]] },
    { "path": "src/HotChocolate/Adapters/src/Adapters.OpenApi.AspNetCore/DynamicOpenApiDocumentTransformer.cs", "ranges": [[207, 207], [211, 211], [213, 216]] }
  ]
}

---

Project coverage: 54.4% (242338/445627 lines)