feat: warn when error response content type is not application/json

docs/spectral-rules.md

@@ -83,6 +83,30 @@ responses:
 
 **Default Severity**: warn
 
+## ibm-error-content-type-is-json
+
+An error response likely returns `application/json` and this rule warns when `application/json` is not the content type. This rule should be ignored when the API actually returns an error response that is not `application/json`.
+
+**Bad Example**
+
+```yaml
+responses:
+  400:
+    content:
+      'application/octet-stream':
+```
+
+**Good Example**
+
+```yaml
+responses:
+  400:
+    content:
+      'application/json':
+```
+
+**Default Severity**: warn
+
 ## major-version-in-path
 
 Validates that every path contains a path segment for the API major version, of the form `v<n>`, and that all paths have the same major version segment. The major version can appear in either the server URL (oas3), the basePath (oas2), or in each path entry.

src/spectral/rulesets/.defaultsForSpectral.yaml

@@ -135,6 +135,17 @@ rules:
     then:
       field: '*/*'
       function: falsy
+  # custom Spectral rule to warn for error response without application/json content
+  ibm-error-content-type-is-json:
+    description: 'error response should support application/json'
+    formats: ["oas3"]
+    severity: warn
+    resolved: true
+    message: "{{description}}"
+    given: $.paths[*][*].responses[?(@property >= 400 && @property < 600)].content
+    then:
+      field: 'application/json'
+      function: truthy
   # custom Spectral rule to ensure response example provided
   response-example-provided:
     message: "{{error}}"

test/spectral/tests/custom-rules/ibm-error-content-type-is-json.test.js

@@ -0,0 +1,59 @@
+const inCodeValidator = require('../../../../src/lib');
+
+describe('spectral - test error response content type is application/json', function() {
+  it('should error only when the error response content type is not application/json', async () => {
+    const spec = {
+      openapi: '3.0.0',
+      paths: {
+        path1: {
+          get: {
+            responses: {
+              '200': {
+                content: {
+                  // no error
+                  'application/octet-stream': {
+                    $ref: '#/components/schemas/GenericSchema'
+                  }
+                }
+              },
+              '400': {
+                content: {
+                  // error 1
+                  'application/octet-stream': {
+                    $ref: '#/components/schemas/GenericSchema'
+                  }
+                }
+              },
+              '404': {
+                content: {
+                  // no error
+                  'application/json': {
+                    $ref: '#/components/schemas/GenericSchema'
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      components: {
+        schemas: {
+          GenericSchema: {
+            type: 'object',
+            properties: {
+              prop: {
+                type: 'string'
+              }
+            }
+          }
+        }
+      }
+    };
+
+    const res = await inCodeValidator(spec, true);
+    const expectedWarnings = res.warnings.filter(
+      warn => warn.message === 'error response should support application/json'
+    );
+    expect(expectedWarnings.length).toBe(1);
+  });
+});