From 2f3af9e23ae184edeba1791e7750300b6126733e Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 15 Dec 2021 17:34:26 -0600 Subject: [PATCH 1/7] docs: add/improve our openapi command warnings --- src/cmds/openapi.js | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/cmds/openapi.js b/src/cmds/openapi.js index df30d7bd5..3810557cc 100644 --- a/src/cmds/openapi.js +++ b/src/cmds/openapi.js @@ -54,11 +54,15 @@ exports.run = async function (opts) { let isUpdate; if (!key && opts.token) { - console.warn('Using `rdme` with --token has been deprecated. Please use `--key` and `--id` instead.'); + console.warn('Warning: `--token` has been deprecated. Please use `--key` and `--id` instead.'); [key, id] = opts.token.split('-'); } + if (version && id) { + console.warn('Warning: `--version` parameter is ignored because `--id` parameter is'); + } + if (!key) { return Promise.reject(new Error('No project API key provided. Please use `--key`.')); } From f34642da03bbc7eec16f7ba2ce799dc03b7c1c75 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 15 Dec 2021 17:48:31 -0600 Subject: [PATCH 2/7] fix: copy and CI --- __tests__/cmds/openapi.test.js | 4 ++-- src/cmds/openapi.js | 8 ++++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/__tests__/cmds/openapi.test.js b/__tests__/cmds/openapi.test.js index 189f4a300..60175def8 100644 --- a/__tests__/cmds/openapi.test.js +++ b/__tests__/cmds/openapi.test.js @@ -144,12 +144,12 @@ describe('rdme openapi', () => { return openapi .run({ spec: require.resolve('@readme/oas-examples/3.1/json/petstore.json'), token: `${key}-${id}`, version }) .then(() => { - expect(console.warn).toHaveBeenCalledTimes(1); + expect(console.warn).toHaveBeenCalledTimes(2); expect(console.log).toHaveBeenCalledTimes(1); const output = getCommandOutput(); - expect(output).toMatch(/using `rdme` with --token has been deprecated/i); + expect(output).toMatch(/The `--token` option has been deprecated/i); mock.done(); }); diff --git a/src/cmds/openapi.js b/src/cmds/openapi.js index 3810557cc..8510b4edf 100644 --- a/src/cmds/openapi.js +++ b/src/cmds/openapi.js @@ -54,13 +54,17 @@ exports.run = async function (opts) { let isUpdate; if (!key && opts.token) { - console.warn('Warning: `--token` has been deprecated. Please use `--key` and `--id` instead.'); + console.warn('Heads up! The `--token` option has been deprecated. Please use `--key` and `--id` instead.'); [key, id] = opts.token.split('-'); } if (version && id) { - console.warn('Warning: `--version` parameter is ignored because `--id` parameter is'); + console.warn( + `Heads up! We'll be using the version associated with the \`--${ + opts.token ? 'token' : 'id' + }\` option, so the \`--version\` option will be ignored.` + ); } if (!key) { From bdef05863f304e0f262a7bf3f551f4be7df279ce Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 15 Dec 2021 17:57:08 -0600 Subject: [PATCH 3/7] docs: updating option descriptions --- src/cmds/openapi.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/cmds/openapi.js b/src/cmds/openapi.js index 8510b4edf..8e5789bbd 100644 --- a/src/cmds/openapi.js +++ b/src/cmds/openapi.js @@ -28,7 +28,7 @@ exports.args = [ { name: 'id', type: String, - description: `Unique identifier for your API definition. Use this if you're resyncing an existing API definition`, + description: `Unique identifier for your API definition. Use this if you're re-uploading an existing API definition`, }, { name: 'token', @@ -38,7 +38,7 @@ exports.args = [ { name: 'version', type: String, - description: 'Project version', + description: 'Project version (this is not necessary if you are passing the `--id` option)', }, { name: 'spec', From 53f6997dd68fe0eedca020b3c5bfbe03436544f9 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 15 Dec 2021 18:06:16 -0600 Subject: [PATCH 4/7] test: use openapi command, update snapshots --- __tests__/__snapshots__/index.test.js.snap | 36 +++++++++++----------- __tests__/index.test.js | 6 ++-- 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/__tests__/__snapshots__/index.test.js.snap b/__tests__/__snapshots__/index.test.js.snap index 5258029ad..f757e4def 100644 --- a/__tests__/__snapshots__/index.test.js.snap +++ b/__tests__/__snapshots__/index.test.js.snap @@ -2,24 +2,24 @@ exports[`cli --help should not surface args that are designated as hidden 1`] = ` " -Alias for \`rdme openapi\`. [deprecated] +Upload, or resync, your OpenAPI/Swagger definition to ReadMe. Usage - rdme swagger [file] [options] + rdme openapi [file] [options] Options --key string Project API key - --id string Unique identifier for your API definition. Use this if you're resyncing an + --id string Unique identifier for your API definition. Use this if you're re-uploading an existing API definition - --version string Project version + --version string Project version (this is not necessary if you are passing the \`--id\` option) -h, --help Display this usage guide Related commands - $ rdme openapi Upload, or resync, your OpenAPI/Swagger definition to ReadMe. - $ rdme validate Validate your OpenAPI/Swagger definition. + $ rdme validate Validate your OpenAPI/Swagger definition. + $ rdme swagger Alias for \`rdme openapi\`. [deprecated] " `; @@ -171,47 +171,47 @@ To get more help with ReadMe, check out our docs at https://docs.readme.com. exports[`cli --help should print usage for a given command 1`] = ` " -Alias for \`rdme openapi\`. [deprecated] +Upload, or resync, your OpenAPI/Swagger definition to ReadMe. Usage - rdme swagger [file] [options] + rdme openapi [file] [options] Options --key string Project API key - --id string Unique identifier for your API definition. Use this if you're resyncing an + --id string Unique identifier for your API definition. Use this if you're re-uploading an existing API definition - --version string Project version + --version string Project version (this is not necessary if you are passing the \`--id\` option) -h, --help Display this usage guide Related commands - $ rdme openapi Upload, or resync, your OpenAPI/Swagger definition to ReadMe. - $ rdme validate Validate your OpenAPI/Swagger definition. + $ rdme validate Validate your OpenAPI/Swagger definition. + $ rdme swagger Alias for \`rdme openapi\`. [deprecated] " `; exports[`cli --help should print usage for a given command if supplied as \`help \` 1`] = ` " -Alias for \`rdme openapi\`. [deprecated] +Upload, or resync, your OpenAPI/Swagger definition to ReadMe. Usage - rdme swagger [file] [options] + rdme openapi [file] [options] Options --key string Project API key - --id string Unique identifier for your API definition. Use this if you're resyncing an + --id string Unique identifier for your API definition. Use this if you're re-uploading an existing API definition - --version string Project version + --version string Project version (this is not necessary if you are passing the \`--id\` option) -h, --help Display this usage guide Related commands - $ rdme openapi Upload, or resync, your OpenAPI/Swagger definition to ReadMe. - $ rdme validate Validate your OpenAPI/Swagger definition. + $ rdme validate Validate your OpenAPI/Swagger definition. + $ rdme swagger Alias for \`rdme openapi\`. [deprecated] " `; diff --git a/__tests__/index.test.js b/__tests__/index.test.js index 12018f670..d1c79e4a8 100644 --- a/__tests__/index.test.js +++ b/__tests__/index.test.js @@ -69,15 +69,15 @@ describe('cli', () => { }); it('should print usage for a given command', async () => { - await expect(cli(['swagger', '--help'])).resolves.toMatchSnapshot(); + await expect(cli(['openapi', '--help'])).resolves.toMatchSnapshot(); }); it('should print usage for a given command if supplied as `help `', async () => { - await expect(cli(['help', 'swagger'])).resolves.toMatchSnapshot(); + await expect(cli(['help', 'openapi'])).resolves.toMatchSnapshot(); }); it('should not surface args that are designated as hidden', async () => { - await expect(cli(['swagger', '--help'])).resolves.toMatchSnapshot(); + await expect(cli(['openapi', '--help'])).resolves.toMatchSnapshot(); }); it('should show related commands for a subcommands help menu', async () => { From 4d5efc91ca05713311d5d7e108381f8444a4e355 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 15 Dec 2021 18:10:19 -0600 Subject: [PATCH 5/7] revert: don't change command description I'd have to either update this everywhere (which would be false) or update the test which feels like a lot at the moment --- __tests__/__snapshots__/index.test.js.snap | 6 +++--- src/cmds/openapi.js | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/__tests__/__snapshots__/index.test.js.snap b/__tests__/__snapshots__/index.test.js.snap index f757e4def..9ff826790 100644 --- a/__tests__/__snapshots__/index.test.js.snap +++ b/__tests__/__snapshots__/index.test.js.snap @@ -13,7 +13,7 @@ Upload, or resync, your OpenAPI/Swagger definition to ReadMe. --key string Project API key --id string Unique identifier for your API definition. Use this if you're re-uploading an existing API definition - --version string Project version (this is not necessary if you are passing the \`--id\` option) + --version string Project version -h, --help Display this usage guide Related commands @@ -182,7 +182,7 @@ Upload, or resync, your OpenAPI/Swagger definition to ReadMe. --key string Project API key --id string Unique identifier for your API definition. Use this if you're re-uploading an existing API definition - --version string Project version (this is not necessary if you are passing the \`--id\` option) + --version string Project version -h, --help Display this usage guide Related commands @@ -205,7 +205,7 @@ Upload, or resync, your OpenAPI/Swagger definition to ReadMe. --key string Project API key --id string Unique identifier for your API definition. Use this if you're re-uploading an existing API definition - --version string Project version (this is not necessary if you are passing the \`--id\` option) + --version string Project version -h, --help Display this usage guide Related commands diff --git a/src/cmds/openapi.js b/src/cmds/openapi.js index 8e5789bbd..e0ab98f7b 100644 --- a/src/cmds/openapi.js +++ b/src/cmds/openapi.js @@ -38,7 +38,7 @@ exports.args = [ { name: 'version', type: String, - description: 'Project version (this is not necessary if you are passing the `--id` option)', + description: 'Project version', }, { name: 'spec', From 0574ff1f71aaf14cd86aa8db7d65d4b18654c492 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 16 Dec 2021 10:20:26 -0800 Subject: [PATCH 6/7] docs: make warnings yellow, add lil :warning: emoji --- src/cmds/openapi.js | 12 ++++++++---- src/cmds/swagger.js | 3 ++- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/src/cmds/openapi.js b/src/cmds/openapi.js index e0ab98f7b..00a63205b 100644 --- a/src/cmds/openapi.js +++ b/src/cmds/openapi.js @@ -54,16 +54,20 @@ exports.run = async function (opts) { let isUpdate; if (!key && opts.token) { - console.warn('Heads up! The `--token` option has been deprecated. Please use `--key` and `--id` instead.'); + console.warn( + chalk.yellow('⚠️ Warning! The `--token` option has been deprecated. Please use `--key` and `--id` instead.') + ); [key, id] = opts.token.split('-'); } if (version && id) { console.warn( - `Heads up! We'll be using the version associated with the \`--${ - opts.token ? 'token' : 'id' - }\` option, so the \`--version\` option will be ignored.` + chalk.yellow( + `⚠️ Warning! We'll be using the version associated with the \`--${ + opts.token ? 'token' : 'id' + }\` option, so the \`--version\` option will be ignored.` + ) ); } diff --git a/src/cmds/swagger.js b/src/cmds/swagger.js index 19fc5f7e3..06d5e56a6 100644 --- a/src/cmds/swagger.js +++ b/src/cmds/swagger.js @@ -1,3 +1,4 @@ +const chalk = require('chalk'); const openapi = require('./openapi'); exports.command = 'swagger'; @@ -10,6 +11,6 @@ exports.hiddenArgs = openapi.hiddenArgs; exports.args = openapi.args; exports.run = async function (opts) { - console.warn('`rdme swagger` has been deprecated. Please use `rdme openapi` instead.'); + console.warn(chalk.yellow('⚠️ Warning! `rdme swagger` has been deprecated. Please use `rdme openapi` instead.')); return openapi.run(opts); }; From bec10bcc3b709295a6eb9bb317a9f9b96283d033 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 16 Dec 2021 10:20:42 -0800 Subject: [PATCH 7/7] test: add test for version/id warning --- __tests__/cmds/openapi.test.js | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/__tests__/cmds/openapi.test.js b/__tests__/cmds/openapi.test.js index 60175def8..ab640bda8 100644 --- a/__tests__/cmds/openapi.test.js +++ b/__tests__/cmds/openapi.test.js @@ -154,6 +154,26 @@ describe('rdme openapi', () => { mock.done(); }); }); + + it('should return warning if providing `id` and `version`', () => { + const mock = nock(config.host) + .put(`/api/v1/api-specification/${id}`, body => body.match('form-data; name="spec"')) + .basicAuth({ user: key }) + .reply(201, { id: 1 }, { location: exampleRefLocation }); + + return openapi + .run({ spec: require.resolve('@readme/oas-examples/3.1/json/petstore.json'), key, id, version }) + .then(() => { + expect(console.warn).toHaveBeenCalledTimes(1); + expect(console.log).toHaveBeenCalledTimes(1); + + const output = getCommandOutput(); + + expect(output).toMatch(/the `--version` option will be ignored/i); + + mock.done(); + }); + }); }); describe('versioning', () => {