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