fix(ibm-request-and-response-content): exempt minimally represented resource PUTs

packages/ruleset/src/functions/api-symmetry.js

@@ -1,5 +1,5 @@
 /**
- * Copyright 2023 IBM Corporation.
+ * Copyright 2023 - 2024 IBM Corporation.
  * SPDX-License-Identifier: Apache2.0
  */
 

packages/ruleset/src/functions/index.js

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

packages/ruleset/src/functions/request-and-response-content.js

@@ -0,0 +1,93 @@
+/**
+ * Copyright 2024 IBM Corporation.
+ * SPDX-License-Identifier: Apache2.0
+ */
+
+const { isObject } = require('@ibm-cloud/openapi-ruleset-utilities');
+const {
+ LoggerFactory,
+ pathHasMinimallyRepresentedResource,
+} = require('../utils');
+
+let ruleId;
+let logger;
+
+/**
+ * The implementation for this rule makes assumptions that are dependent on the
+ * presence of the following other rules:
+ *
+ * ibm-operation-responses - all operations define a response
+ *
+ */
+
+module.exports = function requestAndResponseContent(
+ operation,
+ options,
+ context
+) {
+ if (!logger) {
+ ruleId = context.rule.name;
+ logger = LoggerFactory.getInstance().getLogger(ruleId);
+ }
+ return checkForContent(
+ operation,
+ context.path,
+ context.documentInventory.resolved
+ );
+};
+
+/**
+ * This function checks to ensure an operation defines "content" on its
+ * requestBody and responses, when appropriate.
+ *
+ * @param {*} operation - openapi operation object
+ * @param {*} path - path to current openapi artifact, as a list
+ * @param {*} apidef - resolved api spec
+ * @returns an array containing the violations found or [] if no violations
+ */
+function checkForContent(operation, path, apidef) {
+ const errors = [];
+
+ // Check request body for every operation.
+ if (
+ isObject(operation.requestBody) &&
+ !isObject(operation.requestBody.content)
+ ) {
+ errors.push({
+ message: '', // Use rule-defined message.
+ path: [...path, 'requestBody'],
+ });
+ }
+
+ // Check response bodies for the following operations.
+ if (
+ ['get', 'post', 'put', 'patch', 'delete'].includes(path.at(-1)) &&
+ isObject(operation.responses)
+ ) {
+ for (const [statusCode, response] of Object.entries(operation.responses)) {
+ // Skip exempt status codes.
+ if (['204', '202', '101', '304'].includes(statusCode)) {
+ continue;
+ }
+
+ // A PUT operation for a minimally represented resource (i.e. GET returns a 204)
+ // is allowed to define a 201 response with no content.
+ if (
+ path.at(-1) === 'put' &&
+ statusCode === '201' &&
+ pathHasMinimallyRepresentedResource(path.at(-2), apidef, logger, ruleId)
+ ) {
+ continue;
+ }
+
+ if (!isObject(response.content)) {
+ errors.push({
+ message: '',
+ path: [...path, 'responses', statusCode],
+ });
+ }
+ }
+ }
+
+ return errors;
+}

packages/ruleset/src/functions/response-status-codes.js

@@ -1,5 +1,5 @@
 /**
- * Copyright 2017 - 2023 IBM Corporation.
+ * Copyright 2017 - 2024 IBM Corporation.
  * SPDX-License-Identifier: Apache2.0
  */
 
@@ -9,6 +9,7 @@ const {
  isOperationOfType,
  getResourceSpecificSiblingPath,
  getResponseCodes,
+ pathHasMinimallyRepresentedResource,
 } = require('../utils');
 
 let ruleId;
@@ -184,30 +185,10 @@ function hasBodyRepresentation(path, apidef) {
  return;
  }
 
- const resourceGetOperation = apidef.paths[resourceSpecificPath].get;
- if (!resourceGetOperation) {
- logger.debug(
- `${ruleId}: no GET operation found at path "${resourceSpecificPath}"`
- );
- return;
- }
-
- if (!resourceGetOperation.responses) {
- logger.debug(
- `${ruleId}: no responses defined on GET operation at path "${resourceSpecificPath}"`
- );
- return;
- }
-
- const [, getOpSuccessCodes] = getResponseCodes(
- resourceGetOperation.responses
+ return !pathHasMinimallyRepresentedResource(
+ resourceSpecificPath,
+ apidef,
+ logger,
+ ruleId
  );
-
- logger.debug(
- `${ruleId}: corresponding GET operation has the following status codes: ${getOpSuccessCodes.join(
- ', '
- )}`
- );
-
- return !getOpSuccessCodes.includes('204');
 }

packages/ruleset/src/ibm-oas.js

@@ -162,7 +162,7 @@ module.exports = {
  ibmRules.propertyConsistentNameAndType,
  'ibm-property-description': ibmRules.propertyDescriptionExists,
  'ibm-ref-pattern': ibmRules.refPattern,
- 'ibm-request-and-response-content': ibmRules.contentExists,
+ 'ibm-request-and-response-content': ibmRules.requestAndResponseContent,
  'ibm-requestbody-is-object': ibmRules.requestBodyIsObject,
  'ibm-requestbody-name': ibmRules.requestBodyNameExists,
  'ibm-resource-response-consistency': ibmRules.resourceResponseConsistency,

packages/ruleset/src/rules/index.js

@@ -16,7 +16,6 @@ module.exports = {
  collectionArrayProperty: require('./collection-array-property'),
  consecutivePathSegments: require('./consecutive-path-segments'),
  contentContainsSchema: require('./content-contains-schema'),
- contentExists: require('./content-exists'),
  contentTypeHeader: require('./content-type-header'),
  contentTypeIsSpecific: require('./content-type-is-specific'),
  deleteBody: require('./delete-body'),
@@ -61,6 +60,7 @@ module.exports = {
  propertyNameCollision: require('./property-name-collision'),
  refPattern: require('./ref-pattern'),
  refSiblingDuplicateDescription: require('./ref-sibling-duplicate-description'),
+ requestAndResponseContent: require('./request-and-response-content'),
  requestBodyIsObject: require('./requestbody-is-object'),
  requestBodyNameExists: require('./requestbody-name-exists'),
  requiredPropertyMissing: require('./required-property-missing'),

packages/ruleset/src/rules/request-and-response-content.js

@@ -0,0 +1,22 @@
+/**
+ * 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 { requestAndResponseContent } = require('../functions');
+
+module.exports = {
+ description:
+ 'Request bodies and non-204 responses should define a content object',
+ given: operations,
+ severity: 'warn',
+ formats: [oas3],
+ resolved: true,
+ then: {
+ function: requestAndResponseContent,
+ },
+};

packages/ruleset/src/utils/index.js

@@ -1,5 +1,5 @@
 /**
- * Copyright 2017 - 2023 IBM Corporation.
+ * Copyright 2017 - 2024 IBM Corporation.
  * SPDX-License-Identifier: Apache2.0
  */
 
@@ -19,6 +19,7 @@ module.exports = {
  LoggerFactory: require('./logger-factory'),
  mergeAllOfSchemaProperties: require('./merge-allof-schema-properties'),
  operationMethods: require('./constants'),
+ pathHasMinimallyRepresentedResource: require('./path-has-minimally-represented-resource'),
  pathMatchesRegexp: require('./path-matches-regexp'),
  ...require('./mimetype-utils'),
  ...require('./pagination-utils'),

packages/ruleset/src/utils/path-has-minimally-represented-resource.js

@@ -0,0 +1,59 @@
+/**
+ * Copyright 2024 IBM Corporation.
+ * SPDX-License-Identifier: Apache2.0
+ */
+
+const getResponseCodes = require('./get-response-codes');
+
+/**
+ * This function checks for a "minimally represented resource" (i.e. a resource
+ * with no body representation) path. The path is considered to have a minimally
+ * represented resource if the GET request on the path returns a 204 response.
+ *
+ * @param {string} path - the resource-specific path to check
+ * @param {*} apidef - resolved api spec
+ * @param {*} logger - logger object passed from rule, to maintain scope
+ * @param {string} ruleId - name of current rule, to maintain scope
+ * @returns {bool} true if the resource on this path is minimally represented
+ */
+function pathHasMinimallyRepresentedResource(path, apidef, logger, ruleId) {
+ // This should only be true when the path is resource-specific
+ // (i.e. ends with a path parameter).
+ if (!path.endsWith('}')) {
+ logger.debug(`${ruleId}: path "${path}" is not for a specific resource`);
+ return false;
+ }
+
+ const pathItem = apidef.paths[path];
+ if (!pathItem) {
+ logger.debug(`${ruleId}: path "${path}" does not exist`);
+ return false;
+ }
+
+ const resourceGetOperation = pathItem.get;
+ if (!resourceGetOperation) {
+ logger.debug(`${ruleId}: no GET operation found at path "${path}"`);
+ return false;
+ }
+
+ if (!resourceGetOperation.responses) {
+ logger.debug(
+ `${ruleId}: no responses defined on GET operation at path "${path}"`
+ );
+ return false;
+ }
+
+ const [, getOpSuccessCodes] = getResponseCodes(
+ resourceGetOperation.responses
+ );
+
+ logger.debug(
+ `${ruleId}: corresponding GET operation has the following status codes: ${getOpSuccessCodes.join(
+ ', '
+ )}`
+ );
+
+ return getOpSuccessCodes.includes('204');
+}
+
+module.exports = pathHasMinimallyRepresentedResource;

packages/ruleset/test/content-exists.test.js → packages/ruleset/test/request-and-response-content.test.js

@@ -1,13 +1,13 @@
 /**
- * Copyright 2017 - 2023 IBM Corporation.
+ * Copyright 2017 - 2024 IBM Corporation.
  * SPDX-License-Identifier: Apache2.0
  */
 
-const { contentExists } = require('../src/rules');
+const { requestAndResponseContent } = require('../src/rules');
 const { makeCopy, rootDocument, testRule, severityCodes } = require('./utils');
 
 const ruleId = 'ibm-request-and-response-content';
-const rule = contentExists;
+const rule = requestAndResponseContent;
 
 describe(`Spectral rule: ${ruleId}`, () => {
  it('should not error with a clean spec', async () => {
@@ -121,6 +121,31 @@ describe(`Spectral rule: ${ruleId}`, () => {
  expect(results).toHaveLength(0);
  });
 
+ it('should not error if 201 response for PUT on minimally represented resource is missing content', async () => {
+ const testDocument = makeCopy(rootDocument);
+ testDocument.paths['/v1/movies/{id}/genres/{genre}'] = {
+ get: {
+ operationId: 'check_movie_genre',
+ responses: {
+ 204: {
+ description: 'No content - checked',
+ },
+ },
+ },
+ put: {
+ operationId: 'add_movie_genre',
+ responses: {
+ 201: {
+ description: 'No content - created',
+ },
+ },
+ },
+ };
+
+ const results = await testRule(ruleId, rule, testDocument);
+ expect(results).toHaveLength(0);
+ });
+
  it('should error if 201 response is missing content', async () => {
  const testDocument = makeCopy(rootDocument);
  testDocument.paths['/v1/movies'].post = {