From e035db0fbf3391ebab50db024af6e12842e19154 Mon Sep 17 00:00:00 2001 From: Reuven Harrison Date: Mon, 3 Feb 2025 20:57:35 +0200 Subject: [PATCH] enable more unit tests --- checker/check_api_deprecation_test.go | 3 +- .../check_request_parameter_deprecation.go | 21 +- ...heck_request_parameter_deprecation_test.go | 190 ++++++++---------- checker/localizations/localizations.go | 4 +- checker/localizations_src/en/messages.yaml | 2 + .../deprecated-no-sunset-alpha-stability.yaml | 23 +++ docs/BREAKING-CHANGES-EXAMPLES.md | 15 +- docs/DEPRECATION.md | 9 +- 8 files changed, 147 insertions(+), 120 deletions(-) create mode 100644 data/param-deprecation/deprecated-no-sunset-alpha-stability.yaml diff --git a/checker/check_api_deprecation_test.go b/checker/check_api_deprecation_test.go index 57efb225..d17decd6 100644 --- a/checker/check_api_deprecation_test.go +++ b/checker/check_api_deprecation_test.go @@ -100,7 +100,7 @@ func TestBreaking_DeprecationWithoutSunsetWithPolicy(t *testing.T) { errs := checker.CheckBackwardCompatibility(c, d, osm) require.Len(t, errs, 1) require.Equal(t, checker.APIDeprecatedSunsetMissingId, errs[0].GetId()) - require.Equal(t, "sunset date is missing for deprecated API", errs[0].GetText(checker.NewDefaultLocalizer())) + require.Equal(t, "sunset date is missing for deprecated API", errs[0].GetUncolorizedText(checker.NewDefaultLocalizer())) } // BC: deprecating an operation with a default deprecation policy but without specifying sunset date is not breaking @@ -195,6 +195,7 @@ func TestBreaking_DeprecationWithProperSunset(t *testing.T) { errs := checker.CheckBackwardCompatibilityUntilLevel(c, d, osm, checker.INFO) require.Len(t, errs, 1) // only a non-breaking change detected + require.Equal(t, checker.EndpointDeprecatedId, errs[0].GetId()) require.Equal(t, checker.INFO, errs[0].GetLevel()) require.Equal(t, "endpoint deprecated", errs[0].GetUncolorizedText(checker.NewDefaultLocalizer())) } diff --git a/checker/check_request_parameter_deprecation.go b/checker/check_request_parameter_deprecation.go index 33b84da1..6307ce2c 100644 --- a/checker/check_request_parameter_deprecation.go +++ b/checker/check_request_parameter_deprecation.go @@ -4,6 +4,7 @@ import ( "time" "cloud.google.com/go/civil" + "github.com/getkin/kin-openapi/openapi3" "github.com/tufin/oasdiff/diff" ) @@ -30,6 +31,7 @@ func RequestParameterDeprecationCheck(diffReport *diff.Diff, operationsSources * } op := pathItem.Revision.GetOperation(operation) + opInfo := newOpInfo(config, op, operationsSources, operation, path) for paramLocation, paramItems := range operationDiff.ParametersDiff.Modified { for paramName, paramItem := range paramItems { @@ -55,7 +57,7 @@ func RequestParameterDeprecationCheck(diffReport *diff.Diff, operationsSources * continue } - stability, err := getStabilityLevel(op.Extensions) // TODO: how to handle stability? + stability, err := getStabilityLevel(op.Extensions) if err != nil { // handled in CheckBackwardCompatibility continue @@ -67,7 +69,7 @@ func RequestParameterDeprecationCheck(diffReport *diff.Diff, operationsSources * if !ok { // if deprecation policy is defined and sunset is missing, it's a breaking change if deprecationDays > 0 { - result = append(result, getAPIDeprecatedSunsetMissing(newOpInfo(config, op, operationsSources, operation, path))) + result = append(result, getParameterDeprecatedSunsetMissing(opInfo, param)) } continue } @@ -93,7 +95,7 @@ func RequestParameterDeprecationCheck(diffReport *diff.Diff, operationsSources * result = append(result, NewApiChange( RequestParameterSunsetDateTooSmallId, config, - []any{date, deprecationDays}, + []any{param.In, param.Name, date, deprecationDays}, "", operationsSources, op, @@ -121,3 +123,16 @@ func RequestParameterDeprecationCheck(diffReport *diff.Diff, operationsSources * return result } + +func getParameterDeprecatedSunsetMissing(opInfo opInfo, param *openapi3.Parameter) Change { + return NewApiChange( + RequestParameterDeprecatedSunsetMissingId, + opInfo.config, + []any{param.In, param.Name}, + "", + opInfo.operationsSources, + opInfo.operation, + opInfo.method, + opInfo.path, + ) +} diff --git a/checker/check_request_parameter_deprecation_test.go b/checker/check_request_parameter_deprecation_test.go index 95f5e927..d3e779ca 100644 --- a/checker/check_request_parameter_deprecation_test.go +++ b/checker/check_request_parameter_deprecation_test.go @@ -3,7 +3,9 @@ package checker_test import ( "fmt" "testing" + "time" + "cloud.google.com/go/civil" "github.com/stretchr/testify/require" "github.com/tufin/oasdiff/checker" "github.com/tufin/oasdiff/diff" @@ -32,135 +34,113 @@ func TestBreaking_ParameterDeprecationWithInvalidSunset(t *testing.T) { require.Equal(t, "failed to parse sunset date for the 'query' request parameter 'id': 'sunset date doesn't conform with RFC3339: invalid-date'", errs[0].GetUncolorizedText(checker.NewDefaultLocalizer())) } -// // BC: deprecating an operation without a deprecation policy but without specifying sunset date is not breaking -// func TestBreaking_DeprecationWithoutSunsetNoPolicy(t *testing.T) { +// BC: deprecating a parameter without a deprecation policy but without specifying sunset date is not breaking +func TestBreaking_ParameterDeprecationWithoutSunsetNoPolicy(t *testing.T) { -// s1, err := open(getParameterDeprecationFile("base.yaml")) -// require.NoError(t, err) - -// s2, err := open(getParameterDeprecationFile("deprecated-no-sunset.yaml")) -// require.NoError(t, err) - -// d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) -// require.NoError(t, err) -// c := singleCheckConfig(checker.ParameterDeprecationCheck).WithDeprecation(0, 0) -// errs := checker.CheckBackwardCompatibility(c, d, osm) -// require.Empty(t, errs) -// } - -// // BC: deprecating an operation with a deprecation policy but without specifying sunset date is breaking -// func TestBreaking_DeprecationWithoutSunsetWithPolicy(t *testing.T) { + s1, err := open(getParameterDeprecationFile("base.yaml")) + require.NoError(t, err) -// s1, err := open(getParameterDeprecationFile("base.yaml")) -// require.NoError(t, err) + s2, err := open(getParameterDeprecationFile("deprecated-no-sunset.yaml")) + require.NoError(t, err) -// s2, err := open(getParameterDeprecationFile("deprecated-no-sunset.yaml")) -// require.NoError(t, err) + d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) + require.NoError(t, err) + c := singleCheckConfig(checker.RequestParameterDeprecationCheck).WithDeprecation(0, 0) + errs := checker.CheckBackwardCompatibility(c, d, osm) + require.Empty(t, errs) +} -// d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) -// require.NoError(t, err) -// c := singleCheckConfig(checker.ParameterDeprecationCheck).WithDeprecation(30, 100) -// errs := checker.CheckBackwardCompatibility(c, d, osm) -// require.Len(t, errs, 1) -// require.Equal(t, checker.APIDeprecatedSunsetMissingId, errs[0].GetId()) -// require.Equal(t, "sunset date is missing for deprecated API", errs[0].GetText(checker.NewDefaultLocalizer())) -// } +// BC: deprecating a parameter with a deprecation policy but without specifying sunset date is breaking +func TestBreaking_ParameterDeprecationWithoutSunsetWithPolicy(t *testing.T) { -// // BC: deprecating an operation with a default deprecation policy but without specifying sunset date is not breaking -// func TestBreaking_DeprecationWithoutSunset(t *testing.T) { + s1, err := open(getParameterDeprecationFile("base.yaml")) + require.NoError(t, err) -// s1, err := open(getParameterDeprecationFile("base.yaml")) -// require.NoError(t, err) + s2, err := open(getParameterDeprecationFile("deprecated-no-sunset.yaml")) + require.NoError(t, err) -// s2, err := open(getParameterDeprecationFile("deprecated-no-sunset.yaml")) -// require.NoError(t, err) + d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) + require.NoError(t, err) + c := singleCheckConfig(checker.RequestParameterDeprecationCheck).WithDeprecation(30, 100) + errs := checker.CheckBackwardCompatibility(c, d, osm) + require.Len(t, errs, 1) + require.Equal(t, checker.RequestParameterDeprecatedSunsetMissingId, errs[0].GetId()) + require.Equal(t, "'query' request parameter 'id' was deprecated without sunset date", errs[0].GetUncolorizedText(checker.NewDefaultLocalizer())) +} -// d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) -// require.NoError(t, err) -// c := singleCheckConfig(checker.ParameterDeprecationCheck) -// errs := checker.CheckBackwardCompatibility(c, d, osm) -// require.Empty(t, errs) -// } +// BC: deprecating a parameter with a default deprecation policy but without specifying sunset date is not breaking +func TestBreaking_ParameterDeprecationWithoutSunset(t *testing.T) { -// // BC: deprecating an operation without a deprecation policy and without specifying sunset date is not breaking for alpha level -// func TestBreaking_DeprecationForAlpha(t *testing.T) { + s1, err := open(getParameterDeprecationFile("base.yaml")) + require.NoError(t, err) -// s1, err := open(getParameterDeprecationFile("base-alpha-stability.yaml")) -// require.NoError(t, err) + s2, err := open(getParameterDeprecationFile("deprecated-no-sunset.yaml")) + require.NoError(t, err) -// s2, err := open(getParameterDeprecationFile("deprecated-no-sunset-alpha-stability.yaml")) -// require.NoError(t, err) + d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) + require.NoError(t, err) + c := singleCheckConfig(checker.RequestParameterDeprecationCheck) + errs := checker.CheckBackwardCompatibility(c, d, osm) + require.Empty(t, errs) +} -// d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) -// require.NoError(t, err) -// errs := checker.CheckBackwardCompatibility(singleCheckConfig(checker.ParameterDeprecationCheck), d, osm) -// require.Empty(t, errs) -// } +// BC: deprecating an operation without a deprecation policy and without specifying sunset date is not breaking for alpha level +func TestBreaking_ParameterDeprecationForAlpha(t *testing.T) { -// // BC: deprecating an operation without a deprecation policy and without specifying sunset date is not breaking for draft level -// func TestBreaking_DeprecationForDraft(t *testing.T) { -// s1, err := open(getParameterDeprecationFile("base-alpha-stability.yaml")) -// require.NoError(t, err) -// draft := toJson(t, checker.STABILITY_DRAFT) -// s1.Spec.Paths.Value("/api/test").Get.Extensions["x-stability-level"] = draft + s1, err := open(getParameterDeprecationFile("base-alpha-stability.yaml")) + require.NoError(t, err) -// s2, err := open(getParameterDeprecationFile("deprecated-no-sunset-alpha-stability.yaml")) -// require.NoError(t, err) -// s2.Spec.Paths.Value("/api/test").Get.Extensions["x-stability-level"] = draft + s2, err := open(getParameterDeprecationFile("deprecated-no-sunset-alpha-stability.yaml")) + require.NoError(t, err) -// d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) -// require.NoError(t, err) -// errs := checker.CheckBackwardCompatibility(singleCheckConfig(checker.ParameterDeprecationCheck), d, osm) -// require.Empty(t, errs) -// } + d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) + require.NoError(t, err) + errs := checker.CheckBackwardCompatibility(singleCheckConfig(checker.RequestParameterDeprecationCheck), d, osm) + require.Empty(t, errs) +} -// func toJson(t *testing.T, value string) json.RawMessage { -// t.Helper() -// data, err := json.Marshal(value) -// require.NoError(t, err) -// return data -// } +// BC: deprecating a parameter with a deprecation policy and sunset date before required deprecation period is breaking +func TestBreaking_ParameterDeprecationWithEarlySunset(t *testing.T) { + s1, err := open(getParameterDeprecationFile("base.yaml")) + require.NoError(t, err) -// // BC: deprecating an operation with a deprecation policy and sunset date before required deprecation period is breaking -// func TestBreaking_DeprecationWithEarlySunset(t *testing.T) { -// s1, err := open(getParameterDeprecationFile("base.yaml")) -// require.NoError(t, err) + s2, err := open(getParameterDeprecationFile("deprecated-future.yaml")) + require.NoError(t, err) + sunsetDate := civil.DateOf(time.Now()).AddDays(9).String() -// s2, err := open(getParameterDeprecationFile("deprecated-future.yaml")) -// require.NoError(t, err) -// sunsetDate := civil.DateOf(time.Now()).AddDays(9).String() -// s2.Spec.Paths.Value("/api/test").Get.Extensions[diff.SunsetExtension] = toJson(t, sunsetDate) + s2.Spec.Paths.Value("/api/test").GetOperation("GET").Parameters.GetByInAndName("query", "id").Extensions[diff.SunsetExtension] = toJson(t, sunsetDate) -// d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) -// require.NoError(t, err) -// c := singleCheckConfig(checker.ParameterDeprecationCheck).WithDeprecation(0, 10) -// errs := checker.CheckBackwardCompatibility(c, d, osm) -// require.NotEmpty(t, errs) -// require.Len(t, errs, 1) -// require.Equal(t, checker.APISunsetDateTooSmallId, errs[0].GetId()) -// require.Equal(t, fmt.Sprintf("sunset date '%s' is too small, must be at least '10' days from now", sunsetDate), errs[0].GetUncolorizedText(checker.NewDefaultLocalizer())) -// } + d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) + require.NoError(t, err) + c := singleCheckConfig(checker.RequestParameterDeprecationCheck).WithDeprecation(0, 10) + errs := checker.CheckBackwardCompatibility(c, d, osm) + require.NotEmpty(t, errs) + require.Len(t, errs, 1) + require.Equal(t, checker.RequestParameterSunsetDateTooSmallId, errs[0].GetId()) + require.Equal(t, fmt.Sprintf("'query' request parameter 'id' sunset date '%s' is too small, must be at least '10' days from now", sunsetDate), errs[0].GetUncolorizedText(checker.NewDefaultLocalizer())) +} -// // BC: deprecating an operation with a deprecation policy and sunset date after required deprecation period is not breaking -// func TestBreaking_DeprecationWithProperSunset(t *testing.T) { +// BC: deprecating a parameter with a deprecation policy and sunset date after required deprecation period is not breaking +func TestBreaking_ParameterDeprecationWithProperSunset(t *testing.T) { -// s1, err := open(getParameterDeprecationFile("base.yaml")) -// require.NoError(t, err) + s1, err := open(getParameterDeprecationFile("base.yaml")) + require.NoError(t, err) -// s2, err := open(getParameterDeprecationFile("deprecated-future.yaml")) -// require.NoError(t, err) + s2, err := open(getParameterDeprecationFile("deprecated-future.yaml")) + require.NoError(t, err) -// s2.Spec.Paths.Value("/api/test").Get.Extensions[diff.SunsetExtension] = toJson(t, civil.DateOf(time.Now()).AddDays(10).String()) + s2.Spec.Paths.Value("/api/test").GetOperation("GET").Parameters.GetByInAndName("query", "id").Extensions[diff.SunsetExtension] = toJson(t, civil.DateOf(time.Now()).AddDays(10).String()) -// d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) -// c := singleCheckConfig(checker.ParameterDeprecationCheck).WithDeprecation(0, 10) -// require.NoError(t, err) -// errs := checker.CheckBackwardCompatibilityUntilLevel(c, d, osm, checker.INFO) -// require.Len(t, errs, 1) -// // only a non-breaking change detected -// require.Equal(t, checker.INFO, errs[0].GetLevel()) -// require.Equal(t, "endpoint deprecated", errs[0].GetUncolorizedText(checker.NewDefaultLocalizer())) -// } + d, osm, err := diff.GetWithOperationsSourcesMap(diff.NewConfig(), s1, s2) + c := singleCheckConfig(checker.RequestParameterDeprecationCheck).WithDeprecation(0, 10) + require.NoError(t, err) + errs := checker.CheckBackwardCompatibilityUntilLevel(c, d, osm, checker.INFO) + require.Len(t, errs, 1) + // only a non-breaking change detected + require.Equal(t, checker.RequestParameterDeprecatedId, errs[0].GetId()) + require.Equal(t, checker.INFO, errs[0].GetLevel()) + require.Equal(t, "'query' request parameter 'id' was deprecated", errs[0].GetUncolorizedText(checker.NewDefaultLocalizer())) +} // CL: parameters that became deprecated func TestParameterDeprecated_DetectsDeprecated(t *testing.T) { diff --git a/checker/localizations/localizations.go b/checker/localizations/localizations.go index cc4d5345..cfd846db 100644 --- a/checker/localizations/localizations.go +++ b/checker/localizations/localizations.go @@ -1,6 +1,6 @@ // Code generated by go-localize; DO NOT EDIT. // This file was generated by robots at -// 2025-02-03 11:56:49.387168 +0200 IST m=+0.006454543 +// 2025-02-03 20:44:08.626104 +0200 IST m=+0.006954293 package localizations @@ -218,6 +218,7 @@ var localizations = map[string]string{ "en.messages.request-parameter-default-value-removed": "for the %s request parameter %s, default value %s was removed", "en.messages.request-parameter-default-value-removed-description": "request parameter default value unset", "en.messages.request-parameter-deprecated": "%s request parameter %s was deprecated", + "en.messages.request-parameter-deprecated-sunset-missing": "%s request parameter %s was deprecated without sunset date", "en.messages.request-parameter-enum-value-added": "added the new enum value %s to the %s request parameter %s", "en.messages.request-parameter-enum-value-added-description": "request parameter enum value added", "en.messages.request-parameter-enum-value-removed": "removed the enum value %s from the %s request parameter %s", @@ -279,6 +280,7 @@ var localizations = map[string]string{ "en.messages.request-parameter-removed-comment": "This is a warning because some apps may return an error when receiving a parameter that they do not expect. It is recommended to deprecate the parameter first.", "en.messages.request-parameter-removed-description": "request parameter deleted", "en.messages.request-parameter-removed-with-deprecation": "deleted the %s request parameter %s with deprecation", + "en.messages.request-parameter-sunset-date-too-small": "%s request parameter %s sunset date %s is too small, must be at least %s days from now", "en.messages.request-parameter-sunset-parse": "failed to parse sunset date for the %s request parameter %s: %v", "en.messages.request-parameter-type-changed": "for the %s request parameter %s, the type/format was changed from %s/%s to %s/%s", "en.messages.request-parameter-type-changed-description": "request parameter type changed", diff --git a/checker/localizations_src/en/messages.yaml b/checker/localizations_src/en/messages.yaml index 67761944..9d1099a6 100644 --- a/checker/localizations_src/en/messages.yaml +++ b/checker/localizations_src/en/messages.yaml @@ -27,6 +27,8 @@ endpoint-added: endpoint added endpoint-deprecated: endpoint deprecated endpoint-reactivated: endpoint reactivated request-parameter-reactivated: "%s request parameter %s was reactivated" +request-parameter-deprecated-sunset-missing: "%s request parameter %s was deprecated without sunset date" +request-parameter-sunset-date-too-small: "%s request parameter %s sunset date %s is too small, must be at least %s days from now" request-parameter-deprecated: "%s request parameter %s was deprecated" api-path-removed-without-deprecation: api path removed without deprecation api-path-removed-with-deprecation: api path removed with deprecation diff --git a/data/param-deprecation/deprecated-no-sunset-alpha-stability.yaml b/data/param-deprecation/deprecated-no-sunset-alpha-stability.yaml new file mode 100644 index 00000000..c694758f --- /dev/null +++ b/data/param-deprecation/deprecated-no-sunset-alpha-stability.yaml @@ -0,0 +1,23 @@ +info: + title: Tufin + version: 1.0.0 +openapi: 3.0.3 +paths: + /api/test: + get: + x-stability-level: alpha + parameters: + - $ref: '#/components/parameters/id' + responses: + 200: + description: OK +components: + parameters: + id: + name: id + in: query + required: true + schema: + type: string + description: 'The ID' + deprecated: true diff --git a/docs/BREAKING-CHANGES-EXAMPLES.md b/docs/BREAKING-CHANGES-EXAMPLES.md index 3ae9db75..3044ba96 100644 --- a/docs/BREAKING-CHANGES-EXAMPLES.md +++ b/docs/BREAKING-CHANGES-EXAMPLES.md @@ -61,7 +61,9 @@ These examples are automatically generated from unit tests. [deleting an operation before sunset date is breaking](../checker/check_api_removed_test.go?plain=1#L51) [deleting an operation is breaking](../checker/check_api_removed_test.go?plain=1#L20) [deleting sunset header for a deprecated endpoint is breaking](../checker/check_api_sunset_changed_test.go?plain=1#L11) -[deprecating a parameter with a deprecation policy and an invalid sunset date is breaking](../checker/check_request_parameter_deprecation_test.go?plain=1#L16) +[deprecating a parameter with a deprecation policy and an invalid sunset date is breaking](../checker/check_request_parameter_deprecation_test.go?plain=1#L18) +[deprecating a parameter with a deprecation policy and sunset date before required deprecation period is breaking](../checker/check_request_parameter_deprecation_test.go?plain=1#L102) +[deprecating a parameter with a deprecation policy but without specifying sunset date is breaking](../checker/check_request_parameter_deprecation_test.go?plain=1#L53) [deprecating an operation with a deprecation policy and an invalid stability level is breaking](../checker/check_api_deprecation_test.go?plain=1#L52) [deprecating an operation with a deprecation policy and an invalid sunset date is breaking](../checker/check_api_deprecation_test.go?plain=1#L33) [deprecating an operation with a deprecation policy and sunset date before required deprecation period is breaking](../checker/check_api_deprecation_test.go?plain=1#L161) @@ -146,6 +148,9 @@ These examples are automatically generated from unit tests. [deleting other extension (not sunset) header for a deprecated endpoint is not breaking](../checker/check_api_sunset_changed_test.go?plain=1#L84) [deprecating a header is not breaking](../checker/check_not_breaking_test.go?plain=1#L226) [deprecating a parameter is not breaking](../checker/check_not_breaking_test.go?plain=1#L213) +[deprecating a parameter with a default deprecation policy but without specifying sunset date is not breaking](../checker/check_request_parameter_deprecation_test.go?plain=1#L71) +[deprecating a parameter with a deprecation policy and sunset date after required deprecation period is not breaking](../checker/check_request_parameter_deprecation_test.go?plain=1#L123) +[deprecating a parameter without a deprecation policy but without specifying sunset date is not breaking](../checker/check_request_parameter_deprecation_test.go?plain=1#L37) [deprecating a schema is not breaking](../checker/check_not_breaking_test.go?plain=1#L239) [deprecating an operation with a default deprecation policy but without specifying sunset date is not breaking](../checker/check_api_deprecation_test.go?plain=1#L106) [deprecating an operation with a deprecation policy and sunset date after required deprecation period is not breaking](../checker/check_api_deprecation_test.go?plain=1#L181) @@ -314,10 +319,10 @@ These examples are automatically generated from unit tests. [making request property required, while also giving it a default value](../checker/check_request_property_required_updated_test.go?plain=1#L58) [new header, query and cookie request params](../checker/check_new_request_non_path_parameter_test.go?plain=1#L11) [new paths or path operations](../checker/check_api_added_test.go?plain=1#L11) -[parameters that became deprecated](../checker/check_request_parameter_deprecation_test.go?plain=1#L165) -[parameters that were re-activated](../checker/check_request_parameter_deprecation_test.go?plain=1#L188) -[path operations that became deprecated](../checker/check_api_deprecation_test.go?plain=1#L202) -[path operations that were re-activated](../checker/check_api_deprecation_test.go?plain=1#L225) +[parameters that became deprecated](../checker/check_request_parameter_deprecation_test.go?plain=1#L145) +[parameters that were re-activated](../checker/check_request_parameter_deprecation_test.go?plain=1#L168) +[path operations that became deprecated](../checker/check_api_deprecation_test.go?plain=1#L203) +[path operations that were re-activated](../checker/check_api_deprecation_test.go?plain=1#L226) [removing 'allOf' subschema from the request body or request body property](../checker/check_request_property_all_of_updated_test.go?plain=1#L46) [removing 'allOf' subschema from the response body or response body property](../checker/check_response_property_all_of_updated_test.go?plain=1#L46) [removing 'anyOf' schema from the request body or request body property](../checker/check_request_property_any_of_updated_test.go?plain=1#L46) diff --git a/docs/DEPRECATION.md b/docs/DEPRECATION.md index 7eb6d325..df3775ff 100644 --- a/docs/DEPRECATION.md +++ b/docs/DEPRECATION.md @@ -2,7 +2,7 @@ Sometimes APIs need to be removed, for example, when we replace an old API by a new version. As API owners, we want a process that will allow us to phase out the old API version and transition to the new one smoothly as possible and with minimal disruptions to business. -OpenAPI specification supports a ```deprecated``` flag which can be used to mark operations and other object types as deprecated. +OpenAPI specification supports a ```deprecated``` flag which can be used to mark operations and parameters as deprecated. Deprecating a resource **isn't** considered a breaking change since it doesn't break the client but only serves as an indication of an intent to remove something in the future. After deprecating a resource, it can be removed without triggering a breaking change since the client already knows it is going to be removed. @@ -45,10 +45,9 @@ If you are using [API stability levels](STABILITY.md) you can define different s - Stable APIs: with the `--deprecation-days-stable` - Beta APIs: with the `--deprecation-days-beta` -### Deprecating Parameters and Schemas -OpenAPI 3 supports the `deprecation` field for three objects: Operation, Parameter and Schema. -Oasdiff currently supports deprecation for `Operations` only. -Supporting the other objects is planned too. +### Deprecating Schemas +OpenAPI 3 supports the `deprecation` field for three objects: `Operations`, `Parameters` and `Parameters`. +Oasdiff currently supports deprecation for `Operations` and `Parameters`. ### Notes: 1. Deprecation days can be set to non-negative integers