Report OpenAPI definitions the adapter cannot use

src/HotChocolate/Adapters/src/Adapters.OpenApi.AspNetCore/DynamicOpenApiDocumentTransformer.cs

@@ -58,10 +58,11 @@ public void AddDefinitions(
         OpenApiEndpointDefinition[] endpoints,
         OpenApiModelDefinition[] models,
         IDictionary<string, OpenApiModelDefinition> modelsByName,
-        ISchemaDefinition schema)
+        ISchemaDefinition schema,
+        IOpenApiDiagnosticEvents events)
     {
         var (endpointDescriptors, modelDescriptors, inputComponents) =
-            new DocumentBuilder(schema, modelsByName).Build(endpoints, models);
+            new DocumentBuilder(schema, modelsByName, events).Build(endpoints, models);
 
         _endpoints = endpointDescriptors;
         _models = modelDescriptors;
@@ -180,10 +181,12 @@ public void Add(OpenApiEndpointDefinitionParameter parameter)
     // ambient values (schema, models) are read from fields instead of threaded as parameters.
     private sealed class DocumentBuilder(
         ISchemaDefinition schema,
-        IDictionary<string, OpenApiModelDefinition> modelsByName)
+        IDictionary<string, OpenApiModelDefinition> modelsByName,
+        IOpenApiDiagnosticEvents events)
     {
         private readonly ISchemaDefinition _schema = schema;
         private readonly IDictionary<string, OpenApiModelDefinition> _modelsByName = modelsByName;
+        private readonly IOpenApiDiagnosticEvents _events = events;
         private readonly Dictionary<string, int> _operationIdUsages = [];
         private readonly Dictionary<string, OpenApiSchemaAbstraction> _inputComponents = [];
         private readonly HashSet<string> _registeredInputNames = [];
@@ -201,9 +204,16 @@ private sealed class DocumentBuilder(
                     var endpointDescriptor = CreateEndpointDescriptor(endpoint);
                     endpointDescriptors.Add(endpointDescriptor);
                 }
-                catch
+                catch (Exception exception)
                 {
-                    // If the construction of an endpoint descriptor fails, we just skip over it.
+                    // If the construction of an endpoint descriptor fails, we skip over it and
+                    // report why the endpoint is missing from the OpenAPI document.
+                    var endpointName = endpoint.OperationDefinition.Name?.Value;
+
+                    ReportError(
+                        $"Endpoint '{endpointName}' could not be added to the OpenAPI document: "
+                        + exception.Message,
+                        endpoint);
                 }
             }
 
@@ -214,9 +224,14 @@ private sealed class DocumentBuilder(
                     var modelDescriptor = CreateModelDescriptor(model);
                     modelDescriptors.Add(modelDescriptor);
                 }
-                catch
+                catch (Exception exception)
                 {
-                    // If the construction of an model descriptor fails, we just skip over it.
+                    // If the construction of an model descriptor fails, we skip over it and
+                    // report why the model is missing from the OpenAPI document.
+                    ReportError(
+                        $"Model '{model.Name}' could not be added to the OpenAPI document: "
+                        + exception.Message,
+                        model);
                 }
             }
 
@@ -537,9 +552,22 @@ private OpenApiSchemaAbstraction CreateOpenApiSchemaForSelectionSet(
                     var fieldName = field.Name.Value;
                     var responseName = field.Alias?.Value ?? fieldName;
 
-                    var fieldType = fieldName == IntrospectionFieldNames.TypeName ?
-                        new NonNullType(_schema.Types["String"]) :
-                        ((IComplexTypeDefinition)namedType).Fields[fieldName].Type;
+                    IOutputType fieldType;
+
+                    if (fieldName == IntrospectionFieldNames.TypeName)
+                    {
+                        fieldType = new NonNullType(_schema.Types["String"]);
+                    }
+                    else if (namedType is IComplexTypeDefinition complexType
+                        && complexType.Fields.TryGetField(fieldName, out var fieldDefinition))
+                    {
+                        fieldType = fieldDefinition.Type;
+                    }
+                    else
+                    {
+                        throw new InvalidOperationException(
+                            $"Expected to find field '{fieldName}' on type '{namedType.Name}'.");
+                    }
 
                     OpenApiSchemaAbstraction typeSchema;
                     if (field.SelectionSet is not null)
@@ -622,7 +650,12 @@ private OpenApiSchemaAbstraction CreateOpenApiSchemaForSelectionSet(
                     }
                     else
                     {
-                        var fragment = localFragmentLookup[fragmentName];
+                        if (!localFragmentLookup.TryGetValue(fragmentName, out var fragment))
+                        {
+                            throw new InvalidOperationException(
+                                $"Expected to find a definition for fragment '{fragmentName}'.");
+                        }
+
                         var typeCondition = _schema.Types[fragment.TypeCondition.Name.Value];
                         var isDifferentType = !typeCondition.IsAssignableFrom(namedType);
                         var typeName = typeCondition.Name;
@@ -1301,5 +1334,10 @@ private static string GetOperationId(string? operationName)
                 span[0] = char.ToLowerInvariant(span[0]);
             });
         }
+
+        private void ReportError(string message, IOpenApiDefinition definition)
+        {
+            _events.ValidationErrors([new OpenApiDefinitionValidationError(message, definition)]);
+        }
     }
 }

src/HotChocolate/Adapters/src/Adapters.OpenApi.Core/Execution/OpenApiEndpointDescriptor.cs

@@ -6,12 +6,15 @@ namespace HotChocolate.Adapters.OpenApi;
 
 internal sealed record OpenApiEndpointDescriptor(
     DocumentNode Document,
-    bool HasValidDocument,
+    IReadOnlyList<IError> DocumentErrors,
     string HttpMethod,
     RoutePattern Route,
     VariableValueInsertionTrie ParameterTrie,
     string? VariableFilledThroughBody,
-    OpenApiResponseBodySelection ResponseBodySelection);
+    OpenApiResponseBodySelection ResponseBodySelection)
+{
+    public bool HasValidDocument => DocumentErrors.Count == 0;
+}
 
 internal interface IVariableValueInsertionTrieSegment;
 

src/HotChocolate/Adapters/src/Adapters.OpenApi.Core/Execution/OpenApiEndpointFactory.cs

@@ -73,11 +73,10 @@ public static OpenApiEndpointDescriptor CreateEndpointDescriptor(
         var documentValidator = schema.Services.GetRequiredService<DocumentValidator>();
 
         var validationResult = documentValidator.Validate(schema, document);
-        var hasValidDocument = !validationResult.HasErrors;
 
         return new OpenApiEndpointDescriptor(
             document,
-            hasValidDocument,
+            validationResult.Errors,
             endpointDefinition.HttpMethod,
             route,
             parameterTrie,

src/HotChocolate/Adapters/src/Adapters.OpenApi.Core/IDynamicOpenApiDocumentTransformer.cs

@@ -6,5 +6,6 @@ void AddDefinitions(
         OpenApiEndpointDefinition[] endpoints,
         OpenApiModelDefinition[] models,
         IDictionary<string, OpenApiModelDefinition> modelsByName,
-        ISchemaDefinition schema);
+        ISchemaDefinition schema,
+        IOpenApiDiagnosticEvents events);
 }

src/HotChocolate/Adapters/src/Adapters.OpenApi.Core/OpenApiDefinitionRegistry.cs

@@ -153,12 +153,13 @@ private void UpdateAllDefinitions(
             validDefinitions.Add(definition);
         }
 
-        UpdateEndpointsAndOpenApiDefinitions(validDefinitions, schema);
+        UpdateEndpointsAndOpenApiDefinitions(validDefinitions, schema, events);
     }
 
     private void UpdateEndpointsAndOpenApiDefinitions(
         List<IOpenApiDefinition> definitions,
-        ISchemaDefinition schema)
+        ISchemaDefinition schema,
+        IOpenApiDiagnosticEvents events)
     {
         var endpoints = definitions
             .OfType<OpenApiEndpointDefinition>()
@@ -191,14 +192,23 @@ private void UpdateEndpointsAndOpenApiDefinitions(
                 continue;
             }
 
+            var endpointName = endpoint.OperationDefinition.Name!.Value;
+
             OpenApiEndpointDescriptor descriptor;
 
             try
             {
                 descriptor = OpenApiEndpointFactory.CreateEndpointDescriptor(endpoint, modelsByName, schema);
             }
-            catch
+            catch (Exception exception)
             {
+                events.ValidationErrors(
+                [
+                    new OpenApiDefinitionValidationError(
+                        $"Endpoint '{endpointName}' could not be initialized: {exception.Message}",
+                        endpoint)
+                ]);
+
                 continue;
             }
 
@@ -217,18 +227,35 @@ private void UpdateEndpointsAndOpenApiDefinitions(
 
                 keyHasValid.Add(key);
             }
-            else if (!keyToIndex.ContainsKey(key))
+            else
             {
-                keyToIndex[key] = chosenEndpoints.Count;
-                chosenEndpoints.Add((endpoint, descriptor));
+                events.ValidationErrors(
+                [
+                    .. descriptor.DocumentErrors.Select(
+                        error => new OpenApiDefinitionValidationError(
+                            $"Endpoint '{endpointName}' has an invalid document: {error.Message}",
+                            endpoint))
+                ]);
+
+                if (!keyToIndex.ContainsKey(key))
+                {
+                    keyToIndex[key] = chosenEndpoints.Count;
+                    chosenEndpoints.Add((endpoint, descriptor));
+                }
             }
         }
 
+        // Endpoints with an invalid document cannot execute, so they are left out of the
+        // OpenAPI document rather than described as callable.
         _transformer.AddDefinitions(
-            chosenEndpoints.Select(e => e.Definition).ToArray(),
+            chosenEndpoints
+                .Where(e => e.Descriptor.HasValidDocument)
+                .Select(e => e.Definition)
+                .ToArray(),
             models,
             modelsByName,
-            schema);
+            schema,
+            events);
 
         var httpEndpoints = new List<Endpoint>();