OpenAPI Common Parameters

ALLOF.md

@@ -20,10 +20,10 @@ diff --side-by-side data/allof/simple.yaml data/allof/revision.yaml
 In order to reduce such false-positives, oasdiff supports the ability to replace allOf by a merged equivalent before comparing the specs, like this:
 
 ```
-oasdiff breaking data/allof/simple.yaml data/allof/revision.yaml --flatten
+oasdiff breaking data/allof/simple.yaml data/allof/revision.yaml --flatten-allof
 ```
 In this case no breaking changes are reported, correctly.  
-The `--flatten` flag is also supported with `diff` and `changelog`.
+The `--flatten-allof` flag is also supported with `diff`, `changelog`, `delta` and `summary`.
 
 In order to see how oasdiff merges allOf, you can use the dedicated `flatten` command:
 ```

COMMON-PARAMS.md

@@ -0,0 +1,32 @@
+## Common Parameters
+
+### Common Parameters Definition
+Parameters shared by all operations of a path can be defined on the path level instead of the operation level.  
+Path-level parameters are inherited by all operations of that path.  
+A typical use case are the GET/PUT/PATCH/DELETE operations that manipulate a resource accessed via a path parameter.
+
+### There are two ways to handle Common Parameters in oasdiff
+1. By default, oasdiff compares path parameters and operation parameters separately.
+2. The `--flatten-params` merges common parameters from the path level into the operation level before running the diff.
+
+For example, this command outputs two breaking changes:
+```
+oasdiff changelog data/common-params/params_in_path.yaml data/common-params/params_in_op.yaml
+```
+Output: 
+```
+2 changes: 2 error, 0 warning, 0 info
+error	[new-request-path-parameter] at data/common-params/params_in_op.yaml
+	in API GET /admin/v0/abc/{id}
+		added the new path request parameter 'id'
+
+error	[new-required-request-parameter] at data/common-params/params_in_op.yaml
+	in API GET /admin/v0/abc/{id}
+		added the new required 'header' request parameter 'tenant-id'
+```
+
+
+Adding the `--flatten-params` eliminates the errors:
+```
+oasdiff changelog data/common-params/params_in_path.yaml data/common-params/params_in_op.yaml --flatten-params
+```

README.md

@@ -30,6 +30,7 @@ docker run --rm -t tufin/oasdiff changelog https://raw.githubusercontent.com/Tuf
 - [API deprecation](API-DEPRECATION.md)
 - [Multiple versions of the same endpoint](MATCHING-ENDPOINTS.md)
 - [Merge allOf schemas](ALLOF.md)
+- [Merge common parameters](COMMON-PARAMS.md)
 - [Path prefix modification](#path-prefix-modification)
 - [Path parameter renaming](#path-parameter-renaming)
 - [Excluding certain kinds of changes](#excluding-specific-kinds-of-changes)

checker/checker_breaking_min_max_test.go

@@ -20,7 +20,7 @@ func TestBreaking_RequestMaxLengthSmaller(t *testing.T) {
 	maxLengthTo := uint64(11)
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.MaxLength = &maxLengthTo
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.NotEmpty(t, errs)
@@ -39,7 +39,7 @@ func TestBreaking_ResponseMaxLengthSmaller(t *testing.T) {
 	maxLengthTo := uint64(11)
 	s2.Spec.Paths.Value(securityScorePath).Get.Responses.Value("201").Value.Content["application/xml"].Schema.Value.MaxLength = &maxLengthTo
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Empty(t, errs)
@@ -53,7 +53,7 @@ func TestBreaking_RequestMinLengthSmaller(t *testing.T) {
 	s1.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.MinLength = uint64(13)
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.MinLength = uint64(11)
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Empty(t, errs)
@@ -67,7 +67,7 @@ func TestBreaking_MinLengthSmaller(t *testing.T) {
 	s1.Spec.Paths.Value(securityScorePath).Get.Responses.Value("201").Value.Content["application/xml"].Schema.Value.MinLength = uint64(13)
 	s2.Spec.Paths.Value(securityScorePath).Get.Responses.Value("201").Value.Content["application/xml"].Schema.Value.MinLength = uint64(11)
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Equal(t, checker.ResponseBodyMinLengthDecreasedId, errs[0].GetId())
@@ -84,7 +84,7 @@ func TestBreaking_RequestMaxLengthGreater(t *testing.T) {
 	maxLengthTo := uint64(14)
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.MaxLength = &maxLengthTo
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Empty(t, errs)
@@ -101,7 +101,7 @@ func TestBreaking_ResponseMaxLengthGreater(t *testing.T) {
 	maxLengthTo := uint64(14)
 	s2.Spec.Paths.Value(securityScorePath).Get.Responses.Value("201").Value.Content["application/xml"].Schema.Value.MaxLength = &maxLengthTo
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.NotEmpty(t, errs)
@@ -117,7 +117,7 @@ func TestBreaking_MaxLengthFromNil(t *testing.T) {
 	maxLengthTo := uint64(14)
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.MaxLength = &maxLengthTo
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.NotEmpty(t, errs)
@@ -135,7 +135,7 @@ func TestBreaking_ResponseMaxLengthFromNil(t *testing.T) {
 	maxLengthTo := uint64(14)
 	s2.Spec.Paths.Value(securityScorePath).Get.Responses.Value("201").Value.Content["application/xml"].Schema.Value.MaxLength = &maxLengthTo
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Empty(t, errs)
@@ -151,7 +151,7 @@ func TestBreaking_RequestMaxLengthToNil(t *testing.T) {
 
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.MaxLength = nil
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Empty(t, errs)
@@ -167,7 +167,7 @@ func TestBreaking_ResponseMaxLengthToNil(t *testing.T) {
 
 	s2.Spec.Paths.Value(securityScorePath).Get.Responses.Value("201").Value.Content["application/xml"].Schema.Value.MaxLength = nil
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.NotEmpty(t, errs)
@@ -183,7 +183,7 @@ func TestBreaking_MaxLengthBothNil(t *testing.T) {
 	s1.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.MaxLength = nil
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.MaxLength = nil
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Empty(t, errs)
@@ -197,7 +197,7 @@ func TestBreaking_ResponseMaxLengthBothNil(t *testing.T) {
 	s1.Spec.Paths.Value(securityScorePath).Get.Responses.Value("201").Value.Content["application/xml"].Schema.Value.MaxLength = nil
 	s2.Spec.Paths.Value(securityScorePath).Get.Responses.Value("201").Value.Content["application/xml"].Schema.Value.MaxLength = nil
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Empty(t, errs)
@@ -211,7 +211,7 @@ func TestBreaking_RequestMinItemsSmaller(t *testing.T) {
 	s1.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.MinItems = 13
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.MinItems = 11
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Empty(t, errs)
@@ -225,7 +225,7 @@ func TestBreaking_ResponseMinItemsSmaller(t *testing.T) {
 	s1.Spec.Paths.Value(securityScorePath).Get.Responses.Value("201").Value.Content["application/xml"].Schema.Value.MinItems = 13
 	s2.Spec.Paths.Value(securityScorePath).Get.Responses.Value("201").Value.Content["application/xml"].Schema.Value.MinItems = 11
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.NotEmpty(t, errs)
@@ -241,7 +241,7 @@ func TestBreaking_RequeatMinItemsGreater(t *testing.T) {
 	s1.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.MinItems = 13
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.MinItems = 14
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.NotEmpty(t, errs)
@@ -255,7 +255,7 @@ func TestBreaking_ResponseMinItemsGreater(t *testing.T) {
 	s1.Spec.Paths.Value(securityScorePath).Get.Responses.Value("201").Value.Content["application/xml"].Schema.Value.MinItems = 13
 	s2.Spec.Paths.Value(securityScorePath).Get.Responses.Value("201").Value.Content["application/xml"].Schema.Value.MinItems = 14
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Empty(t, errs)
@@ -272,7 +272,7 @@ func TestBreaking_MaxSmaller(t *testing.T) {
 	maxTo := float64(11)
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInPath, "domain").Schema.Value.Max = &maxTo
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.NotEmpty(t, errs)
@@ -289,7 +289,7 @@ func TestBreaking_MaxSmallerInResponse(t *testing.T) {
 	maxTo := float64(11)
 	s2.Spec.Paths.Value(installCommandPath).Get.Responses.Value("default").Value.Headers["X-RateLimit-Limit"].Value.Schema.Value.Max = &maxTo
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Empty(t, errs)

checker/checker_breaking_property_test.go

@@ -28,7 +28,7 @@ func TestBreaking_NewRequiredProperty(t *testing.T) {
 	}
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInHeader, "network-policies").Schema.Value.Required = []string{"courseId"}
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.NotEmpty(t, errs)
@@ -48,7 +48,7 @@ func TestBreaking_NewNonRequiredProperty(t *testing.T) {
 		},
 	}
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Empty(t, errs)
@@ -72,7 +72,7 @@ func TestBreaking_PropertyRequiredEnabled(t *testing.T) {
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInHeader, "network-policies").Schema.Value.Properties["courseId"] = &sr
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInHeader, "network-policies").Schema.Value.Required = []string{"courseId"}
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.NotEmpty(t, errs)
@@ -98,7 +98,7 @@ func TestBreaking_PropertyRequiredDisabled(t *testing.T) {
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInHeader, "network-policies").Schema.Value.Properties["courseId"] = &sr
 	s2.Spec.Paths.Value(installCommandPath).Get.Parameters.GetByInAndName(openapi3.ParameterInHeader, "network-policies").Schema.Value.Required = []string{}
 
-	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), &s1, &s2)
+	d, osm, err := diff.GetWithOperationsSourcesMap(getConfig(), s1, s2)
 	require.NoError(t, err)
 	errs := checker.CheckBackwardCompatibility(checker.GetDefaultChecks(), d, osm)
 	require.Empty(t, errs)