From c2964744eefc22309e081bc6f58164bde7f1a24a Mon Sep 17 00:00:00 2001 From: Inf1mum Date: Mon, 16 Nov 2026 17:04:13 +0300 Subject: [PATCH] Normalize the 3.1 types keyword when comparing against 3.0 specs What: Comparing two specs that differ only in the openapi version field (e.g. 3.0.1 vs 3.1.0) reported every operation as changed with bogus parameter type changes, flipping the verdict to incompatible. Why: For OpenAPI 3.1 documents the parser stores the type keyword in the JSON Schema 2020-12 types set and leaves Schema.getType() null, while OpenAPI 3.0 documents expose the same keyword only through Schema.getType(). The schema comparison uses the singular type, so identical schemas compared across the version boundary looked like type changes (string -> null). How: Before diffing, when exactly one side of the comparison is an OpenAPI 3.1 document, mirror a single-element types set back into the singular type keyword via the new SchemaTypeNormalizer document walker. A single-element set and the singular type denote the same schema, so this is lossless; sets with zero or multiple types are left untouched and same-version comparisons are unchanged. Adds the specs from the issue as a regression fixture pair. Signed-off-by: Inf1mum --- .../openapidiff/core/compare/OpenApiDiff.java | 23 +++ .../core/utils/SchemaTypeNormalizer.java | 183 ++++++++++++++++++ .../openapidiff/core/Issue858Test.java | 32 +++ core/src/test/resources/issue-858-1.json | 108 +++++++++++ core/src/test/resources/issue-858-2.json | 108 +++++++++++ 5 files changed, 454 insertions(+) create mode 100644 core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypeNormalizer.java create mode 100644 core/src/test/java/org/openapitools/openapidiff/core/Issue858Test.java create mode 100644 core/src/test/resources/issue-858-1.json create mode 100644 core/src/test/resources/issue-858-2.json diff --git a/core/src/main/java/org/openapitools/openapidiff/core/compare/OpenApiDiff.java b/core/src/main/java/org/openapitools/openapidiff/core/compare/OpenApiDiff.java index 59a6f6e1d..bd05d30ae 100644 --- a/core/src/main/java/org/openapitools/openapidiff/core/compare/OpenApiDiff.java +++ b/core/src/main/java/org/openapitools/openapidiff/core/compare/OpenApiDiff.java @@ -18,6 +18,7 @@ import org.openapitools.openapidiff.core.model.deferred.DeferredChanged; import org.openapitools.openapidiff.core.model.deferred.DeferredSchemaCache; import org.openapitools.openapidiff.core.utils.EndpointUtils; +import org.openapitools.openapidiff.core.utils.SchemaTypeNormalizer; public class OpenApiDiff { private PathsDiff pathsDiff; @@ -103,6 +104,7 @@ public OpenApiDiffOptions getOptions() { } private ChangedOpenApi compare() { + normalizeCrossVersionSchemaTypes(); preProcess(oldSpecOpenApi); preProcess(newSpecOpenApi); @@ -146,6 +148,27 @@ private void setChangedExtension(ChangedExtensions changedExtension) { this.changedExtensions = changedExtension; } + /** + * The parser stores the OAS 3.1 {@code type} keyword in the JSON Schema 2020-12 {@code types} set + * and leaves the singular {@code type} null, while OAS 3.0 documents only use the singular {@code + * type}. When comparing across that representation boundary, mirror a single-element {@code + * types} set back into {@code type} so that identical schemas are not reported as type changes + * (see issue 858). Same-version comparisons are left untouched. + */ + private void normalizeCrossVersionSchemaTypes() { + boolean oldSpecIs31 = isOpenApi31(oldSpecOpenApi); + boolean newSpecIs31 = isOpenApi31(newSpecOpenApi); + if (oldSpecIs31 != newSpecIs31) { + SchemaTypeNormalizer.normalize(oldSpecOpenApi); + SchemaTypeNormalizer.normalize(newSpecOpenApi); + } + } + + private static boolean isOpenApi31(OpenAPI openApi) { + String version = openApi.getOpenapi(); + return version != null && version.startsWith("3.1"); + } + private void preProcess(OpenAPI openApi) { List securityRequirements = openApi.getSecurity(); if (securityRequirements != null) { diff --git a/core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypeNormalizer.java b/core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypeNormalizer.java new file mode 100644 index 000000000..374e1df9d --- /dev/null +++ b/core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypeNormalizer.java @@ -0,0 +1,183 @@ +package org.openapitools.openapidiff.core.utils; + +import io.swagger.v3.oas.models.Components; +import io.swagger.v3.oas.models.OpenAPI; +import io.swagger.v3.oas.models.Operation; +import io.swagger.v3.oas.models.PathItem; +import io.swagger.v3.oas.models.media.Content; +import io.swagger.v3.oas.models.media.MediaType; +import io.swagger.v3.oas.models.media.Schema; +import io.swagger.v3.oas.models.parameters.Parameter; +import io.swagger.v3.oas.models.parameters.RequestBody; +import io.swagger.v3.oas.models.responses.ApiResponse; +import java.util.Collections; +import java.util.IdentityHashMap; +import java.util.Map; +import java.util.Set; + +/** + * Mirrors the JSON Schema 2020-12 {@code types} set of a parsed schema back into the singular + * {@code type} keyword when it holds exactly one type. + * + *

For OpenAPI 3.1 documents the parser stores the {@code type} keyword in {@link + * Schema#getTypes()} and leaves {@link Schema#getType()} null, while OpenAPI 3.0 documents expose + * the same keyword only through {@link Schema#getType()}. Comparing a 3.0 document against a 3.1 + * document therefore reports every identical schema as a type change (see issue 858). + * + *

A single-element {@code types} set and the equivalent singular {@code type} denote the same + * schema, so this normalization is lossless for those. Sets with zero or multiple types are left + * untouched because they do not correspond to any singular {@code type} value. + */ +public final class SchemaTypeNormalizer { + + private SchemaTypeNormalizer() {} + + /** Walks the whole document and mirrors single-element {@code types} sets into {@code type}. */ + public static void normalize(OpenAPI openAPI) { + if (openAPI == null) { + return; + } + // Identity-based visited set: schemas can be shared and recursive. + Set visited = Collections.newSetFromMap(new IdentityHashMap<>()); + walkPathItems(openAPI.getPaths(), visited); + walkPathItems(openAPI.getWebhooks(), visited); + + Components components = openAPI.getComponents(); + if (components == null) { + return; + } + walkSchemas(components.getSchemas(), visited); + if (components.getParameters() != null) { + components.getParameters().values().forEach(parameter -> walkParameter(parameter, visited)); + } + if (components.getRequestBodies() != null) { + components + .getRequestBodies() + .values() + .forEach(requestBody -> walkRequestBody(requestBody, visited)); + } + if (components.getResponses() != null) { + components + .getResponses() + .values() + .forEach(apiResponse -> walkApiResponse(apiResponse, visited)); + } + if (components.getHeaders() != null) { + components.getHeaders().values().forEach(header -> walkSchema(header.getSchema(), visited)); + } + walkPathItems(components.getPathItems(), visited); + if (components.getCallbacks() != null) { + components.getCallbacks().values().forEach(callback -> walkPathItems(callback, visited)); + } + } + + private static void walkPathItems(Map pathItems, Set visited) { + if (pathItems != null) { + pathItems.values().forEach(pathItem -> walkPathItem(pathItem, visited)); + } + } + + private static void walkPathItem(PathItem pathItem, Set visited) { + if (pathItem == null || !visited.add(pathItem)) { + return; + } + pathItem.readOperations().forEach(operation -> walkOperation(operation, visited)); + } + + private static void walkOperation(Operation operation, Set visited) { + if (operation == null) { + return; + } + if (operation.getParameters() != null) { + operation.getParameters().forEach(parameter -> walkParameter(parameter, visited)); + } + walkRequestBody(operation.getRequestBody(), visited); + if (operation.getResponses() != null) { + operation.getResponses().values().forEach(response -> walkApiResponse(response, visited)); + } + if (operation.getCallbacks() != null) { + operation.getCallbacks().values().forEach(callback -> walkPathItems(callback, visited)); + } + } + + private static void walkParameter(Parameter parameter, Set visited) { + if (parameter == null) { + return; + } + walkSchema(parameter.getSchema(), visited); + walkContent(parameter.getContent(), visited); + } + + private static void walkRequestBody(RequestBody requestBody, Set visited) { + if (requestBody == null) { + return; + } + walkContent(requestBody.getContent(), visited); + } + + private static void walkApiResponse(ApiResponse apiResponse, Set visited) { + if (apiResponse == null) { + return; + } + walkContent(apiResponse.getContent(), visited); + if (apiResponse.getHeaders() != null) { + apiResponse.getHeaders().values().forEach(header -> walkSchema(header.getSchema(), visited)); + } + } + + private static void walkContent(Content content, Set visited) { + if (content == null) { + return; + } + for (MediaType mediaType : content.values()) { + if (mediaType != null) { + walkSchema(mediaType.getSchema(), visited); + } + } + } + + private static void walkSchemas(Map schemas, Set visited) { + if (schemas != null) { + schemas.values().forEach(schema -> walkSchema(schema, visited)); + } + } + + private static void walkSchema(Schema schema, Set visited) { + if (schema == null || !visited.add(schema)) { + return; + } + normalizeType(schema); + + if (schema.getProperties() != null) { + schema.getProperties().values().forEach(property -> walkSchema(property, visited)); + } + walkSchema(schema.getItems(), visited); + walkSchema(schema.getNot(), visited); + walkSchema(schema.getAdditionalItems(), visited); + walkSchema(schema.getContains(), visited); + walkSchema(schema.getIf(), visited); + walkSchema(schema.getThen(), visited); + walkSchema(schema.getElse(), visited); + if (schema.getAdditionalProperties() instanceof Schema) { + walkSchema((Schema) schema.getAdditionalProperties(), visited); + } + if (schema.getAllOf() != null) { + schema.getAllOf().forEach(item -> walkSchema(item, visited)); + } + if (schema.getAnyOf() != null) { + schema.getAnyOf().forEach(item -> walkSchema(item, visited)); + } + if (schema.getOneOf() != null) { + schema.getOneOf().forEach(item -> walkSchema(item, visited)); + } + if (schema.getPrefixItems() != null) { + schema.getPrefixItems().forEach(item -> walkSchema(item, visited)); + } + } + + private static void normalizeType(Schema schema) { + if (schema.getType() == null && schema.getTypes() != null && schema.getTypes().size() == 1) { + schema.setType(schema.getTypes().iterator().next()); + } + } +} diff --git a/core/src/test/java/org/openapitools/openapidiff/core/Issue858Test.java b/core/src/test/java/org/openapitools/openapidiff/core/Issue858Test.java new file mode 100644 index 000000000..a15f53235 --- /dev/null +++ b/core/src/test/java/org/openapitools/openapidiff/core/Issue858Test.java @@ -0,0 +1,32 @@ +package org.openapitools.openapidiff.core; + +import static org.openapitools.openapidiff.core.TestUtils.assertOpenApiAreEquals; +import static org.openapitools.openapidiff.core.TestUtils.assertSpecUnchanged; + +import org.junit.jupiter.api.Test; + +/** + * The two specs are identical except for the {@code openapi} version field (3.0.1 vs 3.1.0) and + * {@code info.version}. The parser represents the same {@code type} keyword differently for the two + * versions, which used to report every operation as changed. + */ +public class Issue858Test { + + private final String OAS_30_SPEC = "issue-858-1.json"; + private final String OAS_31_SPEC = "issue-858-2.json"; + + @Test + public void testOpenApiVersionOnlyDifference30To31ReportsNoOperationChanges() { + assertOpenApiAreEquals(OAS_30_SPEC, OAS_31_SPEC); + } + + @Test + public void testOpenApiVersionOnlyDifference31To30ReportsNoOperationChanges() { + assertOpenApiAreEquals(OAS_31_SPEC, OAS_30_SPEC); + } + + @Test + public void testOpenApiVersionOnlyDifferenceIsUnchanged() { + assertSpecUnchanged(OAS_30_SPEC, OAS_31_SPEC); + } +} diff --git a/core/src/test/resources/issue-858-1.json b/core/src/test/resources/issue-858-1.json new file mode 100644 index 000000000..b36d472ff --- /dev/null +++ b/core/src/test/resources/issue-858-1.json @@ -0,0 +1,108 @@ +{ + "components": { + "schemas": { + }, + "securitySchemes": { + } + }, + "info": { + "description": "This is the swagger documentation for sample-api. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). ", + "title": "sample-api", + "version": "3.47.0" + }, + "openapi": "3.0.1", + "paths": { + "/sample-api/export": { + "get": { + "description": "Export into MS Excel a list of Annual Accounts Versions.", + "operationId": "exportItems_1", + "parameters": [ + { + "in": "query", + "name": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "sort", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "successful operation" + } + }, + "summary": "Export list of Annual Accounts Versions in excel format", + "tags": [ + "Search" + ] + } + }, + "/sample-api/{id}/actions/CAN": { + "post": { + "description": "Sample description", + "operationId": "cancel_1", + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "schema": { + "format": "int64", + "type": "integer" + } + } + ], + "responses": { + "201": { + "description": "Cancel executed" + } + }, + "summary": "Cancel ACA Version", + "tags": [ + "ACA Workflow actions" + ] + } + }, + "/sample-api/{id}/actions/DEL": { + "post": { + "description": "This method should be used when a user wants to delete a ACA version from the system", + "operationId": "delete_1", + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "schema": { + "format": "int64", + "type": "integer" + } + } + ], + "responses": { + "201": { + "description": "Delete executed" + } + }, + "summary": "Delete ACA Version", + "tags": [ + "ACA Workflow actions" + ] + } + } + }, + "security": [ + ], + "servers": [ + { + "url": "http://sample-server" + } + ] +} \ No newline at end of file diff --git a/core/src/test/resources/issue-858-2.json b/core/src/test/resources/issue-858-2.json new file mode 100644 index 000000000..4ceb2dad1 --- /dev/null +++ b/core/src/test/resources/issue-858-2.json @@ -0,0 +1,108 @@ +{ + "components": { + "schemas": { + }, + "securitySchemes": { + } + }, + "info": { + "description": "This is the swagger documentation for sample-api. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). ", + "title": "sample-api", + "version": "3.48.0" + }, + "openapi": "3.1.0", + "paths": { + "/sample-api/export": { + "get": { + "description": "Export into MS Excel a list of Annual Accounts Versions.", + "operationId": "exportItems_1", + "parameters": [ + { + "in": "query", + "name": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "in": "query", + "name": "sort", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "successful operation" + } + }, + "summary": "Export list of Annual Accounts Versions in excel format", + "tags": [ + "Search" + ] + } + }, + "/sample-api/{id}/actions/CAN": { + "post": { + "description": "Sample description", + "operationId": "cancel_1", + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "schema": { + "format": "int64", + "type": "integer" + } + } + ], + "responses": { + "201": { + "description": "Cancel executed" + } + }, + "summary": "Cancel ACA Version", + "tags": [ + "ACA Workflow actions" + ] + } + }, + "/sample-api/{id}/actions/DEL": { + "post": { + "description": "This method should be used when a user wants to delete a ACA version from the system", + "operationId": "delete_1", + "parameters": [ + { + "in": "path", + "name": "id", + "required": true, + "schema": { + "format": "int64", + "type": "integer" + } + } + ], + "responses": { + "201": { + "description": "Delete executed" + } + }, + "summary": "Delete ACA Version", + "tags": [ + "ACA Workflow actions" + ] + } + } + }, + "security": [ + ], + "servers": [ + { + "url": "http://sample-server" + } + ] +} \ No newline at end of file