feat: add docs/test for disabling rules

Author: danielgtaylor

README.md

@@ -44,6 +44,22 @@ $ docker run -it -v $(pwd):/tmp rest-api-lint:latest /tmp/my-openapi.yaml
 
 The command will return a `0` on success and a `1` if any errors are found. Warnings do not trigger a failure.
 
+### Exceptions & Overrides
+
+When [stoplightio/spectral#747](https://github.com/stoplightio/spectral/issues/747) gets fixed you will be able to provide individual exceptions on a case-by-case basis.
+
+To disable an entire rule, e.g. to support a legacy API, you can provide your own `.spectral.yaml` file in the root of your repo which sets some rules to `false`. Note that this disables the rule for the _entire file_:
+
+```yaml
+rules:
+  iso8601: false
+  server-version: false
+```
+
+It's also possible to set it to `warn`
+
+The `extends` field is automatically added (or appended to) by the linter script to inject the iSP ruleset into your config.
+
 ## License
 
 Copyright © 2020 iStreamPlanet Co., LLC

entrypoint.js

@@ -7,7 +7,7 @@ const { Spectral, isOpenApiv3 } = require('@stoplight/spectral');
 const { stylish } = require('@stoplight/spectral/dist/formatters/stylish');
 
 const SPECTRAL_CONFIG = '.spectral.yaml';
-const ISP_RULES_PREFIX = process.env.ISP_RULES_PREFIX || '';
+const ISP_RULES_PREFIX = process.env.ISP_RULES_PREFIX || './';
 
 // Mapping of Spectral severity to GitHub Actions message level
 const SEV_MAP = ['error', 'warning', 'debug', 'debug'];

fixtures/disable/openapi.yaml

@@ -0,0 +1,43 @@
+openapi: '3.0.0'
+info:
+  version: 1.0.0
+  title: API Fixture
+  description: API fixture description
+  license:
+    name: Apache2
+  contact:
+    email: [email protected]
+servers:
+  - url: https://api.example.com/v1
+tags:
+  - name: Test
+    description: Test tag
+paths:
+  /test:
+    get:
+      summary: Test operation
+      description: Test operation description
+      operationId: test
+      tags:
+        - Test
+      parameters:
+        - name: startedUtc
+          in: query
+          description: Some query param
+          schema:
+            type: string
+        - name: stopped
+          in: query
+          description: Some query param
+          schema:
+            type: string
+        - name: created
+          in: query
+          description: Some query param
+          schema:
+            type: string
+            format: date-time
+            example: 2020-01-01T12:00:00Z
+      responses:
+        '204':
+          description: Response description

test.js

@@ -31,3 +31,24 @@ describe('Linting fixture files', () => {
     });
   });
 });
+
+describe('Disable rules test', () => {
+  it('should pass when rule is disabled', () => {
+    const cwd = process.cwd();
+
+    process.env.ISP_RULES_PREFIX = '../../';
+    process.chdir('fixtures/disable');
+
+    try {
+      const out = execSync('../../entrypoint.js', {
+        stdio: 'pipe',
+        encoding: 'utf8'
+      });
+    } catch (err) {
+      throw new Error(err.stdout);
+    } finally {
+      process.env.ISP_RULES_PREFIX = '';
+      process.chdir(cwd);
+    }
+  });
+});