CLOUDP-271997: IPA-108 - Deletion coverage

tools/spectral/ipa/__tests__/deleteMethod204Response.test.js

@@ -0,0 +1,66 @@
+import testRule from './__helpers__/testRule';
+import { DiagnosticSeverity } from '@stoplight/types';
+
+testRule('xgen-IPA-108-delete-method-return-204-response', [
+  {
+    name: 'valid DELETE with 204',
+    document: {
+      paths: {
+        '/resource/{id}': {
+          delete: {
+            responses: {
+              204: {
+                description: 'Resource deleted',
+              },
+            },
+          },
+        },
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'invalid DELETE missing 204',
+    document: {
+      paths: {
+        '/resource/{id}': {
+          delete: {
+            responses: {
+              200: {
+                description: 'Resource deleted',
+              },
+            },
+          },
+        },
+      },
+    },
+    errors: [
+      {
+        code: 'xgen-IPA-108-delete-method-return-204-response',
+        message: 'DELETE method should return 204 No Content status code http://go/ipa/108',
+        path: ['paths', '/resource/{id}', 'delete'],
+        severity: DiagnosticSeverity.Warning,
+      },
+    ],
+  },
+  {
+    name: 'valid with exception',
+    document: {
+      paths: {
+        '/resource/{id}': {
+          delete: {
+            'x-xgen-IPA-exception': {
+              'xgen-IPA-108-delete-method-return-204-response': 'Legacy API',
+            },
+            responses: {
+              200: {
+                description: 'Resource deleted',
+              },
+            },
+          },
+        },
+      },
+    },
+    errors: [],
+  },
+]);

tools/spectral/ipa/__tests__/deleteMethod404Response.test.js

@@ -0,0 +1,63 @@
+import testRule from './__helpers__/testRule';
+import { DiagnosticSeverity } from '@stoplight/types';
+
+testRule('xgen-IPA-108-delete-include-404-response', [
+  {
+    name: 'valid DELETE with 404',
+    document: {
+      paths: {
+        '/resource/{id}': {
+          delete: {
+            responses: {
+              204: {},
+              404: {
+                description: 'Resource not found',
+              },
+            },
+          },
+        },
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'invalid DELETE missing 404',
+    document: {
+      paths: {
+        '/resource/{id}': {
+          delete: {
+            responses: {
+              204: {},
+            },
+          },
+        },
+      },
+    },
+    errors: [
+      {
+        code: 'xgen-IPA-108-delete-include-404-response',
+        message: 'DELETE method should include 404 status code for not found resources http://go/ipa/108',
+        path: ['paths', '/resource/{id}', 'delete'],
+        severity: DiagnosticSeverity.Warning,
+      },
+    ],
+  },
+  {
+    name: 'valid with exception',
+    document: {
+      paths: {
+        '/resource/{id}': {
+          delete: {
+            'x-xgen-IPA-exception': {
+              'xgen-IPA-108-delete-include-404-response': 'Idempotent delete',
+            },
+            responses: {
+              204: {},
+            },
+          },
+        },
+      },
+    },
+    errors: [],
+  },
+]);

tools/spectral/ipa/__tests__/deleteMethodNoRequestBody.test.js

@@ -0,0 +1,71 @@
+import testRule from './__helpers__/testRule';
+import { DiagnosticSeverity } from '@stoplight/types';
+
+testRule('xgen-IPA-108-delete-request-no-body', [
+  {
+    name: 'valid DELETE without body',
+    document: {
+      paths: {
+        '/resource/{id}': {
+          delete: {
+            responses: {
+              204: {},
+            },
+          },
+        },
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'invalid DELETE with body',
+    document: {
+      paths: {
+        '/resource/{id}': {
+          delete: {
+            requestBody: {
+              content: {
+                'application/vnd.atlas.2024-08-05+json': {
+                  schema: { type: 'object' },
+                },
+              },
+            },
+            responses: {
+              204: {},
+            },
+          },
+        },
+      },
+    },
+    errors: [
+      {
+        code: 'xgen-IPA-108-delete-request-no-body',
+        message: 'DELETE method should not have a request body http://go/ipa/108',
+        path: ['paths', '/resource/{id}', 'delete'],
+        severity: DiagnosticSeverity.Warning,
+      },
+    ],
+  },
+  {
+    name: 'valid with exception',
+    document: {
+      paths: {
+        '/resource/{id}': {
+          delete: {
+            'x-xgen-IPA-exception': {
+              'xgen-IPA-108-delete-request-no-body': 'Bulk delete operation',
+            },
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: { type: 'object' },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    errors: [],
+  },
+]);

tools/spectral/ipa/__tests__/deleteMethodResponseShouldNotHaveSchema.test.js

@@ -0,0 +1,73 @@
+import testRule from './__helpers__/testRule';
+import { DiagnosticSeverity } from '@stoplight/types';
+
+testRule('xgen-IPA-108-delete-response-should-be-empty', [
+  {
+    name: 'valid DELETE with void 204',
+    document: {
+      paths: {
+        '/resource/{id}': {
+          delete: {
+            responses: {
+              204: {},
+            },
+          },
+        },
+      },
+    },
+    errors: [],
+  },
+  {
+    name: 'invalid DELETE with non-void 204',
+    document: {
+      paths: {
+        '/resource/{id}': {
+          delete: {
+            responses: {
+              204: {
+                content: {
+                  'application/vnd.atlas.2023-01-01+json': {
+                    schema: { type: 'object' },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    errors: [
+      {
+        code: 'xgen-IPA-108-delete-response-should-be-empty',
+        message:
+          'DELETE method should return an empty response. The response should not have a schema property and reference to models http://go/ipa/108',
+        path: ['paths', '/resource/{id}', 'delete'],
+        severity: DiagnosticSeverity.Warning,
+      },
+    ],
+  },
+  {
+    name: 'valid with exception',
+    document: {
+      paths: {
+        '/resource/{id}': {
+          delete: {
+            'x-xgen-IPA-exception': {
+              'xgen-IPA-108-delete-response-should-be-empty': 'Legacy API',
+            },
+            responses: {
+              204: {
+                content: {
+                  'application/vnd.atlas.2023-01-01+json': {
+                    schema: { type: 'object' },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    errors: [],
+  },
+]);

tools/spectral/ipa/ipa-spectral.yaml

@@ -6,6 +6,7 @@ extends:
   - ./rulesets/IPA-113.yaml
   - ./rulesets/IPA-123.yaml
   - ./rulesets/IPA-106.yaml
+  - ./rulesets/IPA-108.yaml
 
 overrides:
   - files:

tools/spectral/ipa/rulesets/IPA-108.yaml

@@ -0,0 +1,41 @@
+# IPA-108: Delete
+# http://go/ipa/108
+
+rules:
+  xgen-IPA-108-delete-response-should-be-empty:
+    description: Delete method response should not have schema reference to object http://go/ipa/108
+    message: '{{error}} http://go/ipa/108'
+    severity: warn
+    given: $.paths[*].delete
+    then:
+      function: deleteMethodResponseShouldNotHaveSchema
+
+  xgen-IPA-108-delete-method-return-204-response:
+    description: DELETE method must return 204 No Content
+    message: '{{error}} http://go/ipa/108'
+    severity: warn
+    given: $.paths[*].delete
+    then:
+      function: deleteMethod204Response
+
+  xgen-IPA-108-delete-request-no-body:
+    description: DELETE method must not have request body
+    message: '{{error}} http://go/ipa/108'
+    severity: warn
+    given: $.paths[*].delete
+    then:
+      function: deleteMethodNoRequestBody
+
+  xgen-IPA-108-delete-include-404-response:
+    description: DELETE method must include 404 response and return it when resource not found
+    message: '{{error}} http://go/ipa/108'
+    severity: warn
+    given: $.paths[*].delete
+    then:
+      function: deleteMethod404Response
+
+functions:
+  - deleteMethodResponseShouldNotHaveSchema
+  - deleteMethod204Response
+  - deleteMethodNoRequestBody
+  - deleteMethod404Response

tools/spectral/ipa/rulesets/README.md

@@ -42,6 +42,17 @@ For rule definitions, see [IPA-106.yaml](https://github.com/mongodb/openapi/blob
 | ------------------------------------------------------------------ | -------------------------------------------------------------------------------- | -------- |
 | 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     |
 
+### IPA-108
+
+For rule definitions, see [IPA-108.yaml](https://github.com/mongodb/openapi/blob/main/tools/spectral/ipa/rulesets/IPA-108.yaml).
+
+| Rule Name                                      | Description                                                                         | Severity |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------- | -------- |
+| xgen-IPA-108-delete-response-should-be-empty   | Delete method response should not have schema reference to object http://go/ipa/108 | warn     |
+| xgen-IPA-108-delete-method-return-204-response | DELETE method must return 204 No Content                                            | warn     |
+| xgen-IPA-108-delete-request-no-body            | DELETE method must not have request body                                            | warn     |
+| xgen-IPA-108-delete-include-404-response       | DELETE method must include 404 response and return it when resource not found       | warn     |
+
 ### IPA-109
 
 For rule definitions, see [IPA-109.yaml](https://github.com/mongodb/openapi/blob/main/tools/spectral/ipa/rulesets/IPA-109.yaml).

tools/spectral/ipa/rulesets/functions/deleteMethod204Response.js

@@ -0,0 +1,29 @@
+import { collectAdoption, collectAndReturnViolation, collectException } from './utils/collectionUtils.js';
+import { hasException } from './utils/exceptions.js';
+
+const RULE_NAME = 'xgen-IPA-108-delete-method-return-204-response';
+const ERROR_MESSAGE = 'DELETE method should return 204 No Content status code';
+
+/**
+ * Delete method should return 204 No Content status code
+ *
+ * @param {object} input - The delete operation object
+ * @param {object} _ - Unused
+ * @param {object} context - The context object containing the path
+ */
+export default (input, _, { path }) => {
+  const deleteOp = input;
+  if (!deleteOp) return;
+
+  if (hasException(deleteOp, RULE_NAME)) {
+    collectException(deleteOp, RULE_NAME, path);
+    return;
+  }
+
+  const responses = deleteOp.responses || {};
+  if (!responses['204']) {
+    return collectAndReturnViolation(path, RULE_NAME, ERROR_MESSAGE);
+  }
+
+  collectAdoption(path, RULE_NAME);
+};