feat: add warning, non-204 success response should have response body

- added logic to check for response bodies in non-204 success responses in the oas3 plugin
- added a test to check that a non-204 success response without response body generates a warning
- added a test to check that multiple non-204 success responses without response bodies generates multiple warnings
- updated the README.md to help users resolve potential issue with `npm run link`
- fixed API definitions and tests that define a non-204 success without adding a response body
- ran `npm run fix` to fix styling issues
- updated variable names to be more clear
- added to tests to compare expected messages and paths

README.md

@@ -57,6 +57,8 @@ The `-g` flag installs the tool globally so that the validator can be run from a
 3. Install the dependencies using `npm install`
 4. Build the command line tool by running `npm run link`.
 
+_If you installed the validator using `npm install -g ibm-openapi-validator`, you will need to run `npm uninstall -g ibm-openapi-validator` before running `npm run link`._
+
 ### Platform specific binaries
 It is possible to build platform specific binaries for Linux, MacOS, and Windows that do not depend on having node.js installed.
 

src/plugins/validation/oas3/semantic-validators/responses.js

@@ -9,6 +9,9 @@
 // A 204 response MUST not define a response body
 // https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.5
 
+// Assertation 4:
+// A non-204 success response MUST define a response body
+
 const { walk } = require('../../../utils');
 
 module.exports.validate = function({ jsSpec }, config) {
@@ -57,6 +60,18 @@ module.exports.validate = function({ jsSpec }, config) {
               message
             });
           }
+        } else {
+          for (const successCode of successCodes) {
+            if (successCode != '204' && !obj[successCode].content) {
+              result.warning.push({
+                path: path.concat([successCode]),
+                message:
+                  `A ` +
+                  successCode +
+                  ` response should include a response body. Use 204 for responses without content.`
+              });
+            }
+          }
         }
       }
     }

test/cli-validator/mockFiles/oas3/clean.yml

@@ -54,7 +54,7 @@ paths:
       tags:
         - pets
       responses:
-        '201':
+        '204':
           description: Null response
         default:
           description: unexpected error

test/plugins/validation/oas3/responses.js

@@ -85,8 +85,8 @@ describe('validation plugin - semantic - responses - oas3', function() {
             summary: 'this is a summary',
             operationId: 'operationId',
             responses: {
-              '200': {
-                description: 'successful operation call'
+              '204': {
+                description: 'successful operation call with no response body'
               }
             }
           }
@@ -99,6 +99,92 @@ describe('validation plugin - semantic - responses - oas3', function() {
     expect(res.warnings.length).toEqual(0);
   });
 
+  it('should complain when a non-204 success does not have response body', function() {
+    const config = {
+      responses: {
+        no_response_codes: 'error',
+        no_success_response_codes: 'warning'
+      }
+    };
+
+    const spec = {
+      paths: {
+        '/example': {
+          get: {
+            summary: 'this is a summary',
+            operationId: 'operationId',
+            responses: {
+              '200': {
+                description: 'successful operation call with no response body'
+              }
+            }
+          }
+        }
+      }
+    };
+
+    const res = validate({ jsSpec: spec }, config);
+    expect(res.warnings.length).toEqual(1);
+    expect(res.warnings[0].path).toEqual(['paths', '/example', 'get', 'responses', '200']);
+    expect(res.warnings[0].message).toEqual(
+      `A 200 response should include a response body. Use 204 for responses without content.`
+    );
+  });
+
+  it('should issue multiple warnings when multiple non-204 successes do not have response bodies', function() {
+    const config = {
+      responses: {
+        no_response_codes: 'error',
+        no_success_response_codes: 'warning'
+      }
+    };
+
+    const spec = {
+      paths: {
+        '/example1': {
+          get: {
+            summary: 'this is a summary',
+            operationId: 'operationId_1',
+            responses: {
+              '200': {
+                description: 'first successful response with no response body'
+              },
+              '202': {
+                description: 'second successful response with no response body'
+              }
+            }
+          }
+        },
+        '/example2': {
+          get: {
+            summary: 'this is a summary',
+            operationId: 'operationId_2',
+            responses: {
+              '203': {
+                description: 'third successful response with no response body'
+              }
+            }
+          }
+        }
+      }
+    };
+
+    const res = validate({ jsSpec: spec }, config);
+    expect(res.warnings.length).toEqual(3);
+    expect(res.warnings[0].path).toEqual(['paths', '/example1', 'get', 'responses', '200']);
+    expect(res.warnings[0].message).toEqual(
+      `A 200 response should include a response body. Use 204 for responses without content.`
+    );
+    expect(res.warnings[1].path).toEqual(['paths', '/example1', 'get', 'responses', '202']);
+    expect(res.warnings[1].message).toEqual(
+      `A 202 response should include a response body. Use 204 for responses without content.`
+    );
+    expect(res.warnings[2].path).toEqual(['paths', '/example2', 'get', 'responses', '203']);
+    expect(res.warnings[2].message).toEqual(
+      `A 203 response should include a response body. Use 204 for responses without content.`
+    );
+  });
+
   it('should complain about having only error responses', function() {
     const config = {
       responses: {