fix: preserve OpenAPI 3.1 null branches, schema refs after dedup, and Crystal webhooks

modules/openapi-generator/src/main/java/org/openapitools/codegen/InlineModelResolver.java

@@ -25,6 +25,7 @@
 import io.swagger.v3.oas.models.*;
 import io.swagger.v3.oas.models.PathItem.HttpMethod;
 import io.swagger.v3.oas.models.callbacks.Callback;
+import io.swagger.v3.oas.models.headers.Header;
 import io.swagger.v3.oas.models.media.*;
 import io.swagger.v3.oas.models.parameters.Parameter;
 import io.swagger.v3.oas.models.parameters.RequestBody;
@@ -1256,6 +1257,39 @@ private void deduplicateComponents() {
             rewriteSchemaRefs(schema, refReplacements);
         }
 
+        // Rewrite all $refs in the other component containers that can hold a schema. Only
+        // components/schemas used to be visited, so a reusable response, parameter, request body,
+        // header, callback or path item kept naming the schema that was just removed.
+        Components components = openAPI.getComponents();
+        if (components.getResponses() != null) {
+            for (ApiResponse response : components.getResponses().values()) {
+                rewriteApiResponseRefs(response, refReplacements);
+            }
+        }
+        if (components.getParameters() != null) {
+            for (Parameter parameter : components.getParameters().values()) {
+                rewriteParameterRefs(parameter, refReplacements);
+            }
+        }
+        if (components.getRequestBodies() != null) {
+            for (RequestBody requestBody : components.getRequestBodies().values()) {
+                rewriteContentRefs(requestBody.getContent(), refReplacements);
+            }
+        }
+        rewriteHeaderRefs(components.getHeaders(), refReplacements);
+        if (components.getCallbacks() != null) {
+            for (Callback callback : components.getCallbacks().values()) {
+                for (PathItem callbackPathItem : callback.values()) {
+                    rewritePathItemRefs(callbackPathItem, refReplacements);
+                }
+            }
+        }
+        if (components.getPathItems() != null) {
+            for (PathItem componentPathItem : components.getPathItems().values()) {
+                rewritePathItemRefs(componentPathItem, refReplacements);
+            }
+        }
+
         // Rewrite all $refs in paths
         if (openAPI.getPaths() != null) {
             for (PathItem pathItem : openAPI.getPaths().values()) {
@@ -1286,6 +1320,7 @@ private void rewriteSchemaRefs(Schema schema, Map<String, String> refReplacement
                 schema.set$ref(replacement);
             }
         }
+        rewriteDiscriminatorMapping(schema, refReplacements);
         if (schema.getProperties() != null) {
             for (Object prop : schema.getProperties().values()) {
                 rewriteSchemaRefs((Schema) prop, refReplacements);
@@ -1315,6 +1350,111 @@ private void rewriteSchemaRefs(Schema schema, Map<String, String> refReplacement
         if (schema.getAdditionalProperties() instanceof Schema) {
             rewriteSchemaRefs((Schema) schema.getAdditionalProperties(), refReplacements);
         }
+        // Remaining JSON Schema 2020-12 sub-schema containers. A $ref held in any of these is a
+        // reference like any other and must follow the same rewrite.
+        if (schema.getPatternProperties() != null) {
+            for (Object s : schema.getPatternProperties().values()) {
+                rewriteSchemaRefs((Schema) s, refReplacements);
+            }
+        }
+        if (schema.getDependentSchemas() != null) {
+            for (Object s : schema.getDependentSchemas().values()) {
+                rewriteSchemaRefs((Schema) s, refReplacements);
+            }
+        }
+        if (schema.getPrefixItems() != null) {
+            for (Object s : schema.getPrefixItems()) {
+                rewriteSchemaRefs((Schema) s, refReplacements);
+            }
+        }
+        rewriteSchemaRefs(schema.getIf(), refReplacements);
+        rewriteSchemaRefs(schema.getThen(), refReplacements);
+        rewriteSchemaRefs(schema.getElse(), refReplacements);
+        rewriteSchemaRefs(schema.getContains(), refReplacements);
+        rewriteSchemaRefs(schema.getPropertyNames(), refReplacements);
+        rewriteSchemaRefs(schema.getUnevaluatedItems(), refReplacements);
+        rewriteSchemaRefs(schema.getUnevaluatedProperties(), refReplacements);
+        rewriteSchemaRefs(schema.getAdditionalItems(), refReplacements);
+        rewriteSchemaRefs(schema.getContentSchema(), refReplacements);
+    }
+
+    /** Rewrites $refs in every media type of a Content, including the headers of its encodings. */
+    private void rewriteContentRefs(Content content, Map<String, String> refReplacements) {
+        if (content == null) {
+            return;
+        }
+        for (MediaType mediaType : content.values()) {
+            rewriteSchemaRefs(mediaType.getSchema(), refReplacements);
+            if (mediaType.getEncoding() != null) {
+                for (Encoding encoding : mediaType.getEncoding().values()) {
+                    rewriteHeaderRefs(encoding.getHeaders(), refReplacements);
+                }
+            }
+        }
+    }
+
+    /** Rewrites $refs carried by a map of Headers (schema and content forms). */
+    private void rewriteHeaderRefs(Map<String, Header> headers, Map<String, String> refReplacements) {
+        if (headers == null) {
+            return;
+        }
+        for (Header header : headers.values()) {
+            rewriteSchemaRefs(header.getSchema(), refReplacements);
+            rewriteContentRefs(header.getContent(), refReplacements);
+        }
+    }
+
+    /** Rewrites $refs carried by a Parameter (schema and content forms). */
+    private void rewriteParameterRefs(Parameter parameter, Map<String, String> refReplacements) {
+        if (parameter == null) {
+            return;
+        }
+        rewriteSchemaRefs(parameter.getSchema(), refReplacements);
+        rewriteContentRefs(parameter.getContent(), refReplacements);
+    }
+
+    /** Rewrites $refs carried by an ApiResponse (its content and its headers). */
+    private void rewriteApiResponseRefs(ApiResponse response, Map<String, String> refReplacements) {
+        if (response == null) {
+            return;
+        }
+        rewriteContentRefs(response.getContent(), refReplacements);
+        rewriteHeaderRefs(response.getHeaders(), refReplacements);
+    }
+
+    /**
+     * Rewrites the values of a schema's {@code discriminator.mapping} according to the same
+     * replacement map used for {@code $ref}s. A mapping value is a reference to a schema, but it
+     * is not stored in a {@code $ref} field, so it is missed by plain {@code $ref} rewriting; a
+     * mapping left pointing at a deduplicated-away schema names a model that is never generated.
+     * <p>
+     * Per the OpenAPI specification a mapping value is either a full schema reference
+     * ("#/components/schemas/Foo") or a bare schema name ("Foo"). Both forms are rewritten, and
+     * each keeps the form it was written in.
+     */
+    private void rewriteDiscriminatorMapping(Schema schema, Map<String, String> refReplacements) {
+        if (schema.getDiscriminator() == null || schema.getDiscriminator().getMapping() == null) {
+            return;
+        }
+        Map<String, String> mapping = schema.getDiscriminator().getMapping();
+        for (Map.Entry<String, String> entry : mapping.entrySet()) {
+            String value = entry.getValue();
+            if (value == null) {
+                continue;
+            }
+            if (value.indexOf('/') >= 0) {
+                String replacement = refReplacements.get(value);
+                if (replacement != null) {
+                    entry.setValue(replacement);
+                }
+            } else {
+                // bare schema name: match against the full ref, then write the bare name back
+                String replacement = refReplacements.get("#/components/schemas/" + value);
+                if (replacement != null) {
+                    entry.setValue(replacement.substring(replacement.lastIndexOf('/') + 1));
+                }
+            }
+        }
     }
 
     /**
@@ -1328,30 +1468,24 @@ private void rewritePathItemRefs(PathItem pathItem, Map<String, String> refRepla
         // Path-level parameters
         if (pathItem.getParameters() != null) {
             for (Parameter p : pathItem.getParameters()) {
-                rewriteSchemaRefs(p.getSchema(), refReplacements);
+                rewriteParameterRefs(p, refReplacements);
             }
         }
         // Operations
         for (Operation operation : pathItem.readOperations()) {
             if (operation.getParameters() != null) {
                 for (Parameter p : operation.getParameters()) {
-                    rewriteSchemaRefs(p.getSchema(), refReplacements);
+                    rewriteParameterRefs(p, refReplacements);
                 }
             }
             RequestBody requestBody = operation.getRequestBody();
-            if (requestBody != null && requestBody.getContent() != null) {
-                for (MediaType mediaType : requestBody.getContent().values()) {
-                    rewriteSchemaRefs(mediaType.getSchema(), refReplacements);
-                }
+            if (requestBody != null) {
+                rewriteContentRefs(requestBody.getContent(), refReplacements);
             }
             ApiResponses responses = operation.getResponses();
             if (responses != null) {
                 for (ApiResponse response : responses.values()) {
-                    if (response.getContent() != null) {
-                        for (MediaType mediaType : response.getContent().values()) {
-                            rewriteSchemaRefs(mediaType.getSchema(), refReplacements);
-                        }
-                    }
+                    rewriteApiResponseRefs(response, refReplacements);
                 }
             }
             if (operation.getCallbacks() != null) {

modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/CrystalClientCodegen.java

@@ -626,6 +626,19 @@ public ModelsMap postProcessModels(ModelsMap objs) {
             if (notJsonSerializable) {
                 cm.vendorExtensions.put("x-cr-not-json-serializable", Boolean.TRUE);
             }
+
+            // A required property that is also nullable (OpenAPI 3.1 `anyOf: [T, {type: null}]`,
+            // or `type: [T, "null"]`) is emitted as `T?`, and JSON::Serializable accepts a
+            // document that omits a nilable field. Only a required *non-nullable* property makes
+            // deserialisation of `{}` fail, so the generated spec asserts that only when one exists.
+            boolean hasRequiredNonNullable = false;
+            for (CodegenProperty p : cm.getRequiredVars()) {
+                if (!p.isNullable) {
+                    hasRequiredNonNullable = true;
+                    break;
+                }
+            }
+            cm.vendorExtensions.put("x-cr-has-required-non-nullable", hasRequiredNonNullable);
         }
         // process enum in models (sets isEnum flags on properties)
         ModelsMap processed = postProcessModelsEnum(objs);
@@ -788,8 +801,33 @@ protected void addAdditionPropertiesToCodeGenModel(CodegenModel codegenModel, Sc
     @Override
     public OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<ModelMap> allModels) {
         objs = super.postProcessOperationsWithModels(objs, allModels);
+        processApiGroup(objs, objs.getOperations(), allModels);
+        return objs;
+    }
 
-        OperationMap operations0 = objs.getOperations();
+    /**
+     * OpenAPI 3.1 declares webhooks in a top-level {@code webhooks} object, which the generator
+     * routes here instead of through {@link #postProcessOperationsWithModels}. They are rendered by
+     * the same api template, so they need the same Crystal-specific vendor extensions: without them
+     * the generated class has no name and its parameters no type.
+     */
+    @Override
+    public org.openapitools.codegen.model.WebhooksMap postProcessWebhooksWithModels(
+            org.openapitools.codegen.model.WebhooksMap objs, List<ModelMap> allModels) {
+        objs = super.postProcessWebhooksWithModels(objs, allModels);
+        processApiGroup(objs, objs.getWebhooks(), allModels);
+        return objs;
+    }
+
+    /**
+     * Shared post-processing for one generated api class, whether its operations come from
+     * {@code paths} or from {@code webhooks}.
+     *
+     * @param objs       the template bundle for the api file (also carries specHelperPath)
+     * @param operations the operations to process, or null when the group is empty
+     * @param allModels  every generated model, used to qualify model types and build examples
+     */
+    private void processApiGroup(Map<String, Object> objs, OperationMap operations0, List<ModelMap> allModels) {
         String classname = (operations0 != null) ? operations0.getClassname() : "";
 
         // The api classname is "<apiNamespace>::<rest>" (toApiName prefixes the configured
@@ -824,11 +862,11 @@ public OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<Mo
         specHelperPath.append("spec_helper");
         objs.put("specHelperPath", specHelperPath.toString());
 
-        if (isSkipOperationExample()) {
-            return objs;
+        if (isSkipOperationExample() || operations0 == null) {
+            return;
         }
 
-        OperationMap operations = objs.getOperations();
+        OperationMap operations = operations0;
         HashMap<String, CodegenModel> modelMaps = ModelMap.toCodegenModelMap(allModels);
         HashMap<String, Integer> processedModelMaps = new HashMap<>();
 
@@ -910,8 +948,6 @@ public OperationsMap postProcessOperationsWithModels(OperationsMap objs, List<Mo
             }
             processedModelMaps.clear();
         }
-
-        return objs;
     }
 
     private String constructExampleCode(CodegenParameter codegenParameter, HashMap<String, CodegenModel> modelMaps, HashMap<String, Integer> processedModelMap) {

modules/openapi-generator/src/main/resources/crystal/model_test.mustache

@@ -31,7 +31,7 @@ Spectator.describe {{moduleName}}::{{classname}} do
   end
 {{/vendorExtensions.x-cr-discriminator-map}}
 {{^vendorExtensions.x-cr-discriminator-map}}
-{{^hasRequired}}
+{{^vendorExtensions.x-cr-has-required-non-nullable}}
   describe "JSON round-trip" do
     it "parses an empty JSON object and re-serialises to valid JSON" do
       instance = {{moduleName}}::{{classname}}.from_json("{}")
@@ -46,18 +46,19 @@ Spectator.describe {{moduleName}}::{{classname}} do
       expect(instance.to_h).to be_a(Hash(String, JSON::Any))
     end
   end
-{{/hasRequired}}
-{{#hasRequired}}
+{{/vendorExtensions.x-cr-has-required-non-nullable}}
+{{#vendorExtensions.x-cr-has-required-non-nullable}}
   describe "required-field enforcement" do
     # A required, non-nilable property without a default makes JSON::Serializable
     # reject a document that omits it. (Assumes at least one required field has no
     # default; models where every required field has a default are not present in
-    # the generated samples.)
+    # the generated samples.) A required *nullable* property is emitted as `T?`, which
+    # JSON::Serializable happily defaults to nil, so it cannot carry this assertion.
     it "raises when required properties are missing" do
       expect { {{moduleName}}::{{classname}}.from_json("{}") }.to raise_error(JSON::SerializableError)
     end
   end
-{{/hasRequired}}
+{{/vendorExtensions.x-cr-has-required-non-nullable}}
 {{/vendorExtensions.x-cr-discriminator-map}}
 {{/vendorExtensions.x-cr-not-json-serializable}}
 {{/anyOf}}

modules/openapi-generator/src/main/resources/crystal/partial_model_generic.mustache

@@ -26,7 +26,7 @@
     # {{{.}}}
     {{/description}}
     @[JSON::Field(key: "{{{baseName}}}", emit_null: false)]
-    property {{{name}}} : {{{dataType}}}
+    property {{{name}}} : {{{dataType}}}{{#isNullable}}?{{/isNullable}}
 
     {{/vendorExtensions.x-cr-inherited}}
     {{/requiredVars}}
@@ -43,7 +43,7 @@
 
     {{/vendorExtensions.x-cr-inherited}}
     {{/optionalVars}}
-{{#vars}}{{#vendorExtensions.x-cr-validated}}{{^isContainer}}{{^vendorExtensions.x-cr-inherited}}    validates({{{name}}}, {{{dataType}}}, {{#required}}false{{/required}}{{^required}}true{{/required}}{{#isEnum}}, enum: [{{#allowableValues}}{{#enumVars}}{{{value}}}{{^-last}}, {{/-last}}{{/enumVars}}{{/allowableValues}}]{{/isEnum}}{{#maxLength}}, max_length: {{{maxLength}}}{{/maxLength}}{{#minLength}}, min_length: {{{minLength}}}{{/minLength}}{{#maximum}}, maximum: {{{maximum}}}{{#exclusiveMaximum}}, exclusive_maximum: true{{/exclusiveMaximum}}{{/maximum}}{{#minimum}}, minimum: {{{minimum}}}{{#exclusiveMinimum}}, exclusive_minimum: true{{/exclusiveMinimum}}{{/minimum}}{{#pattern}}, pattern: {{{pattern}}}{{/pattern}}{{#maxItems}}, max_items: {{{maxItems}}}{{/maxItems}}{{#minItems}}, min_items: {{{minItems}}}{{/minItems}})
+{{#vars}}{{#vendorExtensions.x-cr-validated}}{{^isContainer}}{{^vendorExtensions.x-cr-inherited}}    validates({{{name}}}, {{{dataType}}}, {{#required}}{{#isNullable}}true{{/isNullable}}{{^isNullable}}false{{/isNullable}}{{/required}}{{^required}}true{{/required}}{{#isEnum}}, enum: [{{#allowableValues}}{{#enumVars}}{{{value}}}{{^-last}}, {{/-last}}{{/enumVars}}{{/allowableValues}}]{{/isEnum}}{{#maxLength}}, max_length: {{{maxLength}}}{{/maxLength}}{{#minLength}}, min_length: {{{minLength}}}{{/minLength}}{{#maximum}}, maximum: {{{maximum}}}{{#exclusiveMaximum}}, exclusive_maximum: true{{/exclusiveMaximum}}{{/maximum}}{{#minimum}}, minimum: {{{minimum}}}{{#exclusiveMinimum}}, exclusive_minimum: true{{/exclusiveMinimum}}{{/minimum}}{{#pattern}}, pattern: {{{pattern}}}{{/pattern}}{{#maxItems}}, max_items: {{{maxItems}}}{{/maxItems}}{{#minItems}}, min_items: {{{minItems}}}{{/minItems}})
 {{/vendorExtensions.x-cr-inherited}}{{/isContainer}}{{/vendorExtensions.x-cr-validated}}{{/vars}}
     {{#allOf}}
     {{#-first}}
@@ -69,7 +69,7 @@
     {{/discriminator}}
     # Initializes the object
     # @param [Hash] attributes Model attributes in the form of hash
-    def initialize({{#requiredVars}}{{^vendorExtensions.x-cr-inherited}}@{{/vendorExtensions.x-cr-inherited}}{{{name}}} : {{{dataType}}}{{^-last}}, {{/-last}}{{/requiredVars}}{{#hasRequired}}{{#hasOptional}}, {{/hasOptional}}{{/hasRequired}}{{#optionalVars}}{{^vendorExtensions.x-cr-inherited}}@{{/vendorExtensions.x-cr-inherited}}{{{name}}} : {{{dataType}}}? = {{#vendorExtensions.x-cr-default}}{{{vendorExtensions.x-cr-default}}}{{/vendorExtensions.x-cr-default}}{{^vendorExtensions.x-cr-default}}nil{{/vendorExtensions.x-cr-default}}{{^-last}}, {{/-last}}{{/optionalVars}})
+    def initialize({{#requiredVars}}{{^vendorExtensions.x-cr-inherited}}@{{/vendorExtensions.x-cr-inherited}}{{{name}}} : {{{dataType}}}{{#isNullable}}?{{/isNullable}}{{^-last}}, {{/-last}}{{/requiredVars}}{{#hasRequired}}{{#hasOptional}}, {{/hasOptional}}{{/hasRequired}}{{#optionalVars}}{{^vendorExtensions.x-cr-inherited}}@{{/vendorExtensions.x-cr-inherited}}{{{name}}} : {{{dataType}}}? = {{#vendorExtensions.x-cr-default}}{{{vendorExtensions.x-cr-default}}}{{/vendorExtensions.x-cr-default}}{{^vendorExtensions.x-cr-default}}nil{{/vendorExtensions.x-cr-default}}{{^-last}}, {{/-last}}{{/optionalVars}})
 {{#parent}}      super({{{vendorExtensions.x-cr-parent-args}}})
 {{/parent}}    end
 

modules/openapi-generator/src/main/resources/crystal/shard_name.mustache

@@ -21,3 +21,6 @@ require "./{{shardName}}/validation"
 # APIs
 {{#apiInfo}}{{#apis}}require "./{{shardName}}/api/{{classFilename}}"
 {{/apis}}{{/apiInfo}}
+{{#webhooks}}{{#-first}}# Webhooks (OpenAPI 3.1): api classes generated from the top-level `webhooks` object.
+{{/-first}}require "./{{shardName}}/api/{{classFilename}}"
+{{/webhooks}}