feat: migrate validate to openapi:validate (#598)

* feat: migrate validate to `openapi:validate` * fix: don't document `validate` command * test: fix broken snapshot * fix: add deprecation notice
readmeio · Sep 7, 2022 · 7bd081a · 7bd081a
1 parent c8d0b02
commit 7bd081a
Show file tree

Hide file tree

Showing 15 changed files with 167 additions and 105 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -49,10 +49,10 @@ jobs:
           path: oas-examples-repo
           repository: readmeio/oas-examples
 
-      - name: Run `validate` command
+      - name: Run `openapi:validate` command
         uses: ./rdme-repo/
         with:
-          rdme: validate oas-examples-repo/3.1/json/petstore.json
+          rdme: openapi:validate oas-examples-repo/3.1/json/petstore.json
 
       # Docs: https://rdme-test.readme.io
       - name: Run `openapi` command

diff --git a/.github/workflows/simple.yml b/.github/workflows/simple.yml
@@ -14,7 +14,7 @@ jobs:
         uses: actions/checkout@v3
 
       # This is a simple example that runs our `validate` command on a local file.
-      - name: Run `validate` command
+      - name: Run `openapi:validate` command
         uses: ./ # in actual production usage, this value should be 'readmeio/rdme@XX'
         with:
-          rdme: validate __tests__/__fixtures__/ref-oas/petstore.json
+          rdme: openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,13 +6,13 @@ To run test commands from within the repository, run the build and then run your
 
 ```sh
 npm run build
-./bin/rdme validate __tests__/__fixtures__/ref-oas/petstore.json
+./bin/rdme openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
 ```
 
 If you need to debug commands quicker and re-building TS everytime is becoming cumbersome, you can use the debug command, like so:
 
 ```sh
-npm run debug -- validate __tests__/__fixtures__/ref-oas/petstore.json
+npm run debug -- openapi:validate __tests__/__fixtures__/ref-oas/petstore.json
 ```
 
 ## Running GitHub Actions Locally 🐳

diff --git a/README.md b/README.md
@@ -22,7 +22,7 @@ npm install rdme --save-dev
 Once installed in your project, we recommend using `npx` (which is included if you have `npm` installed) to prefix all of your CLI commands. For example:
 
 ```sh
-npx rdme validate [file]
+npx rdme openapi:validate [file]
 ```
 
 To ensure you're getting the latest features and security updates, we recommend using a tool like [Dependabot](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates) to keep `rdme` (and your other dependencies) up-to-date.
@@ -175,7 +175,7 @@ rdme openapi petstore.json --workingDirectory=[path to directory]
 You can also perform a local validation of your API definition without uploading it to ReadMe, which can be useful when constructing or editing your API definition.
 
 ```sh
-rdme validate [path-to-file.json]
+rdme openapi:validate [path-to-file.json]
 ```
 
 Similar to the `openapi` command, you can also [omit the file path](#omitting-the-file-path).

diff --git a/__tests__/__snapshots__/index.test.ts.snap b/__tests__/__snapshots__/index.test.ts.snap
@@ -26,8 +26,8 @@ Options
 
 Related commands
 
-  $ rdme validate         Validate your OpenAPI/Swagger definition.           
-  $ rdme openapi:reduce   Reduce an OpenAPI definition into a smaller subset. 
+  $ rdme openapi:reduce     Reduce an OpenAPI definition into a smaller subset. 
+  $ rdme openapi:validate   Validate your OpenAPI/Swagger definition.           
 "
 `;
 
@@ -57,8 +57,8 @@ Options
 
 Related commands
 
-  $ rdme validate         Validate your OpenAPI/Swagger definition.           
-  $ rdme openapi:reduce   Reduce an OpenAPI definition into a smaller subset. 
+  $ rdme openapi:reduce     Reduce an OpenAPI definition into a smaller subset. 
+  $ rdme openapi:validate   Validate your OpenAPI/Swagger definition.           
 "
 `;
 
@@ -88,8 +88,8 @@ Options
 
 Related commands
 
-  $ rdme validate         Validate your OpenAPI/Swagger definition.           
-  $ rdme openapi:reduce   Reduce an OpenAPI definition into a smaller subset. 
+  $ rdme openapi:reduce     Reduce an OpenAPI definition into a smaller subset. 
+  $ rdme openapi:validate   Validate your OpenAPI/Swagger definition.           
 "
 `;
 

diff --git a/.../cmds/__snapshots__/validate.test.ts.snap → ...enapi/__snapshots__/validate.test.ts.snap b/.../cmds/__snapshots__/validate.test.ts.snap → ...enapi/__snapshots__/validate.test.ts.snap
@@ -1,6 +1,6 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt (github flag enabled) 1`] = `
+exports[`rdme openapi:validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt (github flag enabled) 1`] = `
 "
 Your GitHub Actions workflow file has been created! ✨
 
@@ -10,7 +10,7 @@ Almost done! Push your newly created file (.github/workflows/validate-test-opt-s
 "
 `;
 
-exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt (github flag enabled) 2`] = `
+exports[`rdme openapi:validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt (github flag enabled) 2`] = `
 "# This GitHub Actions workflow was auto-generated by the \`rdme\` cli on 2022-01-01T00:00:00.000Z
 # You can view our full documentation here: https://docs.readme.com/docs/rdme
 name: ReadMe GitHub Action 🦉
@@ -24,20 +24,20 @@ on:
       - validate-test-opt-spec-github-branch
 
 jobs:
-  rdme-validate:
+  rdme-openapi-validate:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repo 📚
         uses: actions/checkout@v3
 
-      - name: Run \`validate\` command 🚀
+      - name: Run \`openapi:validate\` command 🚀
         uses: readmeio/rdme@7.8.9
         with:
-          rdme: validate __tests__/__fixtures__/petstore-simple-weird-version.json
+          rdme: openapi:validate __tests__/__fixtures__/petstore-simple-weird-version.json
 "
 `;
 
-exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt (including workingDirectory) 1`] = `
+exports[`rdme openapi:validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt (including workingDirectory) 1`] = `
 "
 Your GitHub Actions workflow file has been created! ✨
 
@@ -47,7 +47,7 @@ Almost done! Push your newly created file (.github/workflows/validate-test-opt-s
 "
 `;
 
-exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt (including workingDirectory) 2`] = `
+exports[`rdme openapi:validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt (including workingDirectory) 2`] = `
 "# This GitHub Actions workflow was auto-generated by the \`rdme\` cli on 2022-01-01T00:00:00.000Z
 # You can view our full documentation here: https://docs.readme.com/docs/rdme
 name: ReadMe GitHub Action 🦉
@@ -61,20 +61,20 @@ on:
       - validate-test-opt-spec-github-branch
 
 jobs:
-  rdme-validate:
+  rdme-openapi-validate:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repo 📚
         uses: actions/checkout@v3
 
-      - name: Run \`validate\` command 🚀
+      - name: Run \`openapi:validate\` command 🚀
         uses: readmeio/rdme@7.8.9
         with:
-          rdme: validate petstore.json --workingDirectory=./__tests__/__fixtures__/relative-ref-oas
+          rdme: openapi:validate petstore.json --workingDirectory=./__tests__/__fixtures__/relative-ref-oas
 "
 `;
 
-exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt 1`] = `
+exports[`rdme openapi:validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt 1`] = `
 "
 Your GitHub Actions workflow file has been created! ✨
 
@@ -84,7 +84,7 @@ Almost done! Push your newly created file (.github/workflows/validate-test-opt-s
 "
 `;
 
-exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt 2`] = `
+exports[`rdme openapi:validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via opt 2`] = `
 "# This GitHub Actions workflow was auto-generated by the \`rdme\` cli on 2022-01-01T00:00:00.000Z
 # You can view our full documentation here: https://docs.readme.com/docs/rdme
 name: ReadMe GitHub Action 🦉
@@ -98,20 +98,20 @@ on:
       - validate-test-opt-spec-branch
 
 jobs:
-  rdme-validate:
+  rdme-openapi-validate:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repo 📚
         uses: actions/checkout@v3
 
-      - name: Run \`validate\` command 🚀
+      - name: Run \`openapi:validate\` command 🚀
         uses: readmeio/rdme@7.8.9
         with:
-          rdme: validate __tests__/__fixtures__/petstore-simple-weird-version.json
+          rdme: openapi:validate __tests__/__fixtures__/petstore-simple-weird-version.json
 "
 `;
 
-exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via prompts 1`] = `
+exports[`rdme openapi:validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via prompts 1`] = `
 "
 Your GitHub Actions workflow file has been created! ✨
 
@@ -121,7 +121,7 @@ Almost done! Push your newly created file (.github/workflows/validate-test-file.
 "
 `;
 
-exports[`rdme validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via prompts 2`] = `
+exports[`rdme openapi:validate GHA onboarding E2E tests should create GHA workflow if user passes in spec via prompts 2`] = `
 "# This GitHub Actions workflow was auto-generated by the \`rdme\` cli on 2022-01-01T00:00:00.000Z
 # You can view our full documentation here: https://docs.readme.com/docs/rdme
 name: ReadMe GitHub Action 🦉
@@ -135,20 +135,20 @@ on:
       - validate-test-branch
 
 jobs:
-  rdme-validate:
+  rdme-openapi-validate:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repo 📚
         uses: actions/checkout@v3
 
-      - name: Run \`validate\` command 🚀
+      - name: Run \`openapi:validate\` command 🚀
         uses: readmeio/rdme@7.8.9
         with:
-          rdme: validate __tests__/__fixtures__/petstore-simple-weird-version.json
+          rdme: openapi:validate __tests__/__fixtures__/petstore-simple-weird-version.json
 "
 `;
 
-exports[`rdme validate error handling should throw an error if an invalid OpenAPI 3.1 definition is supplied 1`] = `
+exports[`rdme openapi:validate error handling should throw an error if an invalid OpenAPI 3.1 definition is supplied 1`] = `
 [SyntaxError: OpenAPI schema validation failed.
 
 REQUIRED must have required property 'name'
@@ -162,7 +162,7 @@ REQUIRED must have required property 'name'
   29 |     }]
 `;
 
-exports[`rdme validate error handling should throw an error if an invalid Swagger definition is supplied 1`] = `
+exports[`rdme openapi:validate error handling should throw an error if an invalid Swagger definition is supplied 1`] = `
 [SyntaxError: Swagger schema validation failed.
 
 ADDITIONAL PROPERTY must NOT have additional properties

diff --git a/__tests__/cmds/validate.test.ts → __tests__/cmds/openapi/validate.test.ts b/__tests__/cmds/validate.test.ts → __tests__/cmds/openapi/validate.test.ts
@@ -4,20 +4,22 @@ import fs from 'fs';
 import chalk from 'chalk';
 import prompts from 'prompts';
 
-import Command from '../../src/cmds/validate';
-import { after, before } from '../helpers/get-gha-setup';
+import OpenAPIValidateCommand from '../../../src/cmds/openapi/validate';
+import ValidateAliasCommand from '../../../src/cmds/validate';
+import { after, before } from '../../helpers/get-gha-setup';
 
 const testWorkingDir = process.cwd();
 
-const validate = new Command();
+const validate = new OpenAPIValidateCommand();
+const validateAlias = new ValidateAliasCommand();
 
 let consoleSpy;
 
 const getCommandOutput = () => {
   return [consoleSpy.mock.calls.join('\n\n')].filter(Boolean).join('\n\n');
 };
 
-describe('rdme validate', () => {
+describe('rdme openapi:validate', () => {
   beforeEach(() => {
     consoleSpy = jest.spyOn(console, 'info').mockImplementation();
   });
@@ -208,3 +210,34 @@ describe('rdme validate', () => {
     });
   });
 });
+
+describe('rdme validate', () => {
+  let consoleWarnSpy;
+
+  const getWarningCommandOutput = () => {
+    return [consoleWarnSpy.mock.calls.join('\n\n')].filter(Boolean).join('\n\n');
+  };
+
+  beforeEach(() => {
+    consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
+  });
+
+  afterEach(() => {
+    consoleWarnSpy.mockRestore();
+  });
+
+  it('should should `rdme openapi:validate`', async () => {
+    await expect(
+      validateAlias.run({
+        spec: require.resolve('@readme/oas-examples/3.0/json/petstore.json'),
+      })
+    ).resolves.toContain(chalk.green('petstore.json is a valid OpenAPI API definition!'));
+
+    expect(console.warn).toHaveBeenCalledTimes(1);
+
+    const output = getWarningCommandOutput();
+    expect(output).toBe(
+      chalk.yellow('⚠️  Warning! `rdme validate` has been deprecated. Please use `rdme openapi:validate` instead.')
+    );
+  });
+});
diff --git a/__tests__/lib/__snapshots__/commands.test.ts.snap b/__tests__/lib/__snapshots__/commands.test.ts.snap
@@ -37,6 +37,12 @@ Object {
         "description": "Reduce an OpenAPI definition into a smaller subset.",
         "hidden": false,
         "name": "openapi:reduce",
+        "position": 2,
+      },
+      Object {
+        "description": "Validate your OpenAPI/Swagger definition.",
+        "hidden": false,
+        "name": "openapi:validate",
         "position": 3,
       },
       Object {
@@ -46,10 +52,10 @@ Object {
         "position": 4,
       },
       Object {
-        "description": "Validate your OpenAPI/Swagger definition.",
-        "hidden": false,
+        "description": "Alias for \`rdme openapi:validate\` [deprecated].",
+        "hidden": true,
         "name": "validate",
-        "position": 2,
+        "position": 5,
       },
     ],
     "description": "Upload OpenAPI/Swagger definitions",