fix(ibm-requestbody-name): turn rule off by default, is now redundant (…

…#673)

Now that the IBM API Handbook provides firm and robust guidance on schema
naming and we validate for this guidance in 'ibm-schema-naming-convention',
requiring the 'x-codegen-request-body-name' to be specified on relevant
schemas is no longer necessary. It is resulting in APIs having to duplicate
names between the schema name, title, and extension. This rule will remain
in place for teams that wish to use it but this commit turns it off by default.

https://cloud.ibm.com/docs/api-handbook?topic=api-handbook-schemas#naming

Signed-off-by: Dustin Popp <[email protected]>

docs/ibm-cloud-rules.md

@@ -518,9 +518,9 @@ or <code>application/merge-patch+json</code>.</td>
 </tr>
 <tr>
 <td><a href="#ibm-requestbody-name">ibm-requestbody-name</a></td>
-<td>warn</td>
+<td>off</td>
 <td>An operation should specify a request body name (with the <code>x-codegen-request-body-name</code> extension) if its requestBody
-has non-form content.</td>
+has non-form content. <b>This rule is disabled by default.</b></td>
 <td>oas3</td>
 </tr>
 <tr>
@@ -5364,6 +5364,8 @@ it is a good practice to provide the request body name via the extension, especi
 way to infer a logical name for the operation's body parameter.
 <p>This rule analyzes each operation to determine if a request body name is needed, and if so, checks to make sure 
 that the <code>x-codegen-request-body-name</code> extension is set on the operation.
+<br><br>
+<b>This rule is disabled by default. Enable it in your Spectral config file to utilize this validation.</b>
 </td>
 </tr>
 <tr>

packages/ruleset/src/functions/index.js

@@ -54,7 +54,7 @@ module.exports = {
   refPattern: require('./ref-pattern'),
   refSiblingDuplicateDescription: require('./ref-sibling-duplicate-description'),
   requestAndResponseContent: require('./request-and-response-content'),
-  requestBodyNameExists: require('./requestbody-name-exists'),
+  requestBodyName: require('./requestbody-name'),
   requiredProperty: require('./required-property'),
   resourceResponseConsistency: require('./resource-response-consistency'),
   responseExampleExists: require('./response-example-exists'),

packages/ruleset/src/functions/requestbody-name-exists.js → packages/ruleset/src/functions/requestbody-name.js

@@ -1,5 +1,5 @@
 /**
- * Copyright 2017 - 2023 IBM Corporation.
+ * Copyright 2017 - 2024 IBM Corporation.
  * SPDX-License-Identifier: Apache2.0
  */
 
@@ -18,7 +18,7 @@ module.exports = function (operation, _opts, context) {
     logger = LoggerFactory.getInstance().getLogger(ruleId);
   }
 
-  return requestBodyNameExists(operation, context.path);
+  return requestBodyName(operation, context.path);
 };
 
 // Name of the extension that we're looking for.
@@ -36,7 +36,7 @@ const EXTENSION_NAME = 'x-codegen-request-body-name';
  * @param {*} path the array of path segments indicating the "location" of "op" within the API definition
  * @returns an array containing the violations found or [] if no violations
  */
-function requestBodyNameExists(op, path) {
+function requestBodyName(op, path) {
   logger.debug(
     `${ruleId}: checking operation '${op.operationId}' at location: ${path.join(
       '.'

packages/ruleset/src/ibm-oas.js

@@ -169,7 +169,7 @@ module.exports = {
     'ibm-ref-pattern': ibmRules.refPattern,
     'ibm-request-and-response-content': ibmRules.requestAndResponseContent,
     'ibm-requestbody-is-object': ibmRules.requestBodyIsObject,
-    'ibm-requestbody-name': ibmRules.requestBodyNameExists,
+    'ibm-requestbody-name': ibmRules.requestBodyName,
     'ibm-resource-response-consistency': ibmRules.resourceResponseConsistency,
     'ibm-response-status-codes': ibmRules.responseStatusCodes,
     'ibm-schema-casing-convention': ibmRules.schemaCasingConvention,

packages/ruleset/src/rules/index.js

@@ -65,7 +65,7 @@ module.exports = {
   refSiblingDuplicateDescription: require('./ref-sibling-duplicate-description'),
   requestAndResponseContent: require('./request-and-response-content'),
   requestBodyIsObject: require('./requestbody-is-object'),
-  requestBodyNameExists: require('./requestbody-name-exists'),
+  requestBodyName: require('./requestbody-name'),
   requiredPropertyMissing: require('./required-property-missing'),
   resourceResponseConsistency: require('./resource-response-consistency'),
   responseExampleExists: require('./response-example-exists'),

packages/ruleset/src/rules/requestbody-name-exists.js → packages/ruleset/src/rules/requestbody-name.js

@@ -1,23 +1,23 @@
 /**
- * Copyright 2017 - 2023 IBM Corporation.
+ * Copyright 2017 - 2024 IBM Corporation.
  * SPDX-License-Identifier: Apache2.0
  */
 
 const {
   operations,
 } = require('@ibm-cloud/openapi-ruleset-utilities/src/collections');
 const { oas3 } = require('@stoplight/spectral-formats');
-const { requestBodyNameExists } = require('../functions');
+const { requestBodyName } = require('../functions');
 
 module.exports = {
   description:
     'Verifies that operations have the x-codegen-request-body-name extension set when needed',
   message: '{{error}}',
   given: operations,
-  severity: 'warn',
+  severity: 'off',
   formats: [oas3],
   resolved: true,
   then: {
-    function: requestBodyNameExists,
+    function: requestBodyName,
   },
 };

packages/ruleset/test/requestbody-name.test.js

@@ -1,18 +1,27 @@
 /**
- * Copyright 2017 - 2023 IBM Corporation.
+ * Copyright 2017 - 2024 IBM Corporation.
  * SPDX-License-Identifier: Apache2.0
  */
 
-const { requestBodyNameExists } = require('../src/rules');
+const { requestBodyName } = require('../src/rules');
 const { makeCopy, rootDocument, testRule, severityCodes } = require('./utils');
 
 const ruleId = 'ibm-requestbody-name';
-const rule = requestBodyNameExists;
+const rule = requestBodyName;
 const expectedSeverity = severityCodes.warning;
 const expectedMsg = `Operations with non-form request bodies should set a name with the 'x-codegen-request-body-name' extension`;
 
+// This rule is turned off by default - enable it to run tests
+// but still verify it is defined in the rule as "off".
+const originalSeverity = makeCopy(rule.severity);
+rule.severity = 'warn';
+
 // `Operation with non-form requestBody should set a name with the ${EXTENSION_NAME} extension.`
 describe(`Spectral rule: ${ruleId}`, () => {
+  it('Should originally be set to severity: "off"', () => {
+    expect(originalSeverity).toBe('off');
+  });
+
   describe('Should not yield errors', () => {
     it('Clean spec', async () => {
       const results = await testRule(ruleId, rule, rootDocument);