From 6c0b46529c4ab0cbd666f9ddf3edd72da87da4cf Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 13 Mar 2025 10:53:16 +0000 Subject: [PATCH 1/2] Fix: Refine Create method descriptions with the resource collection applicability --- tools/spectral/ipa/rulesets/IPA-106.yaml | 21 ++++++++++++++------ tools/spectral/ipa/rulesets/README.md | 25 ++++++++++++++++-------- 2 files changed, 32 insertions(+), 14 deletions(-) diff --git a/tools/spectral/ipa/rulesets/IPA-106.yaml b/tools/spectral/ipa/rulesets/IPA-106.yaml index 40734d725d..a41a62a074 100644 --- a/tools/spectral/ipa/rulesets/IPA-106.yaml +++ b/tools/spectral/ipa/rulesets/IPA-106.yaml @@ -10,7 +10,9 @@ functions: rules: xgen-IPA-106-create-method-request-body-is-request-suffixed-object: - description: 'The Create method request should be a Request suffixed object. http://go/ipa/106' + description: | + The Create method request should be a Request suffixed object. http://go/ipa/106 + This rule applies only to POST requests targeting resource collection URIs. message: '{{error}} http://go/ipa/106' severity: warn given: '$.paths[*].post.requestBody.content' @@ -18,7 +20,9 @@ rules: field: '@key' function: 'createMethodRequestBodyIsRequestSuffixedObject' xgen-IPA-106-create-method-should-not-have-query-parameters: - description: 'Create operations should not use query parameters. http://go/ipa/106' + description: | + Create operations should not use query parameters. http://go/ipa/106 + This rule applies only to POST requests targeting resource collection URIs. message: '{{error}} http://go/ipa/106' severity: warn given: '$.paths[*].post' @@ -26,8 +30,9 @@ rules: function: 'createMethodShouldNotHaveQueryParameters' xgen-IPA-106-create-method-request-body-is-get-method-response: description: | - Request body content of the Create method and response content of the Get method should refer to the same resource. - readOnly/writeOnly properties will be ignored. http://go/ipa/106 + Request body content of the Create method and response content of the Get method should refer to the same resource. http://go/ipa/106 + readOnly/writeOnly properties will be ignored. + This rule applies only to POST requests targeting resource collection URIs. message: '{{error}} http://go/ipa/106' severity: warn given: '$.paths[*].post.requestBody.content' @@ -37,7 +42,9 @@ rules: functionOptions: ignoredValues: ['readOnly', 'writeOnly'] xgen-IPA-106-create-method-request-has-no-readonly-fields: - description: 'Create method Request object must not include fields with readOnly:true. http://go/ipa/106' + description: | + Create method Request object must not include fields with readOnly:true. http://go/ipa/106 + This rule applies only to POST requests targeting resource collection URIs. message: '{{error}} http://go/ipa/106' severity: warn given: '$.paths[*].post.requestBody.content' @@ -45,7 +52,9 @@ rules: field: '@key' function: 'createMethodRequestHasNoReadonlyFields' xgen-IPA-106-create-method-response-code-is-201: - description: 'Create methods must return a 201 Created response code. http://go/ipa/106' + description: | + Create methods must return a 201 Created response code. http://go/ipa/106 + This rule applies only to POST requests targeting resource collection URIs. message: '{{error}} http://go/ipa/106' severity: warn given: '$.paths[*].post' diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index 386458bb6d..fef1fff619 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/tools/spectral/ipa/rulesets/README.md @@ -53,15 +53,24 @@ For rule definitions, see [IPA-105.yaml](https://github.com/mongodb/openapi/blob For rule definitions, see [IPA-106.yaml](https://github.com/mongodb/openapi/blob/main/tools/spectral/ipa/rulesets/IPA-106.yaml). -| Rule Name | Description | Severity | -| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| xgen-IPA-106-create-method-request-body-is-request-suffixed-object | The Create method request should be a Request suffixed object. http://go/ipa/106 | warn | -| xgen-IPA-106-create-method-should-not-have-query-parameters | Create operations should not use query parameters. http://go/ipa/106 | warn | -| xgen-IPA-106-create-method-request-body-is-get-method-response | Request body content of the Create method and response content of the Get method should refer to the same resource. -readOnly/writeOnly properties will be ignored. http://go/ipa/106 +| Rule Name | Description | Severity | +| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| xgen-IPA-106-create-method-request-body-is-request-suffixed-object | The Create method request should be a Request suffixed object. http://go/ipa/106 +This rule applies only to POST requests targeting resource collection URIs. + | warn | +| xgen-IPA-106-create-method-should-not-have-query-parameters | Create operations should not use query parameters. http://go/ipa/106 +This rule applies only to POST requests targeting resource collection URIs. + | warn | +| xgen-IPA-106-create-method-request-body-is-get-method-response | Request body content of the Create method and response content of the Get method should refer to the same resource. http://go/ipa/106 +readOnly/writeOnly properties will be ignored. +This rule applies only to POST requests targeting resource collection URIs. | warn | -| xgen-IPA-106-create-method-request-has-no-readonly-fields | Create method Request object must not include fields with readOnly:true. http://go/ipa/106 | warn | -| xgen-IPA-106-create-method-response-code-is-201 | Create methods must return a 201 Created response code. http://go/ipa/106 | warn | +| xgen-IPA-106-create-method-request-has-no-readonly-fields | Create method Request object must not include fields with readOnly:true. http://go/ipa/106 +This rule applies only to POST requests targeting resource collection URIs. + | warn | +| xgen-IPA-106-create-method-response-code-is-201 | Create methods must return a 201 Created response code. http://go/ipa/106 +This rule applies only to POST requests targeting resource collection URIs. + | warn | ### IPA-108 From 7cfd34a184d6ca759d9f2d2332d3a4fa6feb6af0 Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 13 Mar 2025 11:07:25 +0000 Subject: [PATCH 2/2] address the comments --- tools/spectral/ipa/rulesets/IPA-106.yaml | 10 +++++----- tools/spectral/ipa/rulesets/README.md | 25 +++++++----------------- 2 files changed, 12 insertions(+), 23 deletions(-) diff --git a/tools/spectral/ipa/rulesets/IPA-106.yaml b/tools/spectral/ipa/rulesets/IPA-106.yaml index a41a62a074..d04cec321d 100644 --- a/tools/spectral/ipa/rulesets/IPA-106.yaml +++ b/tools/spectral/ipa/rulesets/IPA-106.yaml @@ -10,7 +10,7 @@ functions: rules: xgen-IPA-106-create-method-request-body-is-request-suffixed-object: - description: | + description: >- The Create method request should be a Request suffixed object. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs. message: '{{error}} http://go/ipa/106' @@ -20,7 +20,7 @@ rules: field: '@key' function: 'createMethodRequestBodyIsRequestSuffixedObject' xgen-IPA-106-create-method-should-not-have-query-parameters: - description: | + description: >- Create operations should not use query parameters. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs. message: '{{error}} http://go/ipa/106' @@ -29,7 +29,7 @@ rules: then: function: 'createMethodShouldNotHaveQueryParameters' xgen-IPA-106-create-method-request-body-is-get-method-response: - description: | + description: >- Request body content of the Create method and response content of the Get method should refer to the same resource. http://go/ipa/106 readOnly/writeOnly properties will be ignored. This rule applies only to POST requests targeting resource collection URIs. @@ -42,7 +42,7 @@ rules: functionOptions: ignoredValues: ['readOnly', 'writeOnly'] xgen-IPA-106-create-method-request-has-no-readonly-fields: - description: | + description: >- Create method Request object must not include fields with readOnly:true. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs. message: '{{error}} http://go/ipa/106' @@ -52,7 +52,7 @@ rules: field: '@key' function: 'createMethodRequestHasNoReadonlyFields' xgen-IPA-106-create-method-response-code-is-201: - description: | + description: >- Create methods must return a 201 Created response code. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs. message: '{{error}} http://go/ipa/106' diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index fef1fff619..68dc2e78c1 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/tools/spectral/ipa/rulesets/README.md @@ -53,24 +53,13 @@ For rule definitions, see [IPA-105.yaml](https://github.com/mongodb/openapi/blob For rule definitions, see [IPA-106.yaml](https://github.com/mongodb/openapi/blob/main/tools/spectral/ipa/rulesets/IPA-106.yaml). -| Rule Name | Description | Severity | -| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -| xgen-IPA-106-create-method-request-body-is-request-suffixed-object | The Create method request should be a Request suffixed object. http://go/ipa/106 -This rule applies only to POST requests targeting resource collection URIs. - | warn | -| xgen-IPA-106-create-method-should-not-have-query-parameters | Create operations should not use query parameters. http://go/ipa/106 -This rule applies only to POST requests targeting resource collection URIs. - | warn | -| xgen-IPA-106-create-method-request-body-is-get-method-response | Request body content of the Create method and response content of the Get method should refer to the same resource. http://go/ipa/106 -readOnly/writeOnly properties will be ignored. -This rule applies only to POST requests targeting resource collection URIs. - | warn | -| xgen-IPA-106-create-method-request-has-no-readonly-fields | Create method Request object must not include fields with readOnly:true. http://go/ipa/106 -This rule applies only to POST requests targeting resource collection URIs. - | warn | -| xgen-IPA-106-create-method-response-code-is-201 | Create methods must return a 201 Created response code. http://go/ipa/106 -This rule applies only to POST requests targeting resource collection URIs. - | warn | +| Rule Name | Description | Severity | +| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| xgen-IPA-106-create-method-request-body-is-request-suffixed-object | The Create method request should be a Request suffixed object. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs. | warn | +| xgen-IPA-106-create-method-should-not-have-query-parameters | Create operations should not use query parameters. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs. | warn | +| xgen-IPA-106-create-method-request-body-is-get-method-response | Request body content of the Create method and response content of the Get method should refer to the same resource. http://go/ipa/106 readOnly/writeOnly properties will be ignored. This rule applies only to POST requests targeting resource collection URIs. | warn | +| xgen-IPA-106-create-method-request-has-no-readonly-fields | Create method Request object must not include fields with readOnly:true. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs. | warn | +| xgen-IPA-106-create-method-response-code-is-201 | Create methods must return a 201 Created response code. http://go/ipa/106 This rule applies only to POST requests targeting resource collection URIs. | warn | ### IPA-108