From 2228c2cfb16abb2356780837ec88198a2e3f69b9 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 16 Dec 2021 10:42:21 -0800 Subject: [PATCH] docs: add/improve our command warnings (#406) * docs: add/improve our openapi command warnings * fix: copy and CI * docs: updating option descriptions * test: use openapi command, update snapshots * 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 * docs: make warnings yellow, add lil :warning: emoji * test: add test for version/id warning --- __tests__/__snapshots__/index.test.js.snap | 30 +++++++++++----------- __tests__/cmds/openapi.test.js | 22 +++++++++++++++- __tests__/index.test.js | 6 ++--- src/cmds/openapi.js | 16 ++++++++++-- src/cmds/swagger.js | 3 ++- 5 files changed, 55 insertions(+), 22 deletions(-) diff --git a/__tests__/__snapshots__/index.test.js.snap b/__tests__/__snapshots__/index.test.js.snap index 5258029ad..9ff826790 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 -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 -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 -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__/cmds/openapi.test.js b/__tests__/cmds/openapi.test.js index 189f4a300..ab640bda8 100644 --- a/__tests__/cmds/openapi.test.js +++ b/__tests__/cmds/openapi.test.js @@ -143,13 +143,33 @@ 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(2); + expect(console.log).toHaveBeenCalledTimes(1); + + const output = getCommandOutput(); + + expect(output).toMatch(/The `--token` option has been deprecated/i); + + 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(/using `rdme` with --token has been deprecated/i); + expect(output).toMatch(/the `--version` option will be ignored/i); mock.done(); }); 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 () => { diff --git a/src/cmds/openapi.js b/src/cmds/openapi.js index df30d7bd5..00a63205b 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', @@ -54,11 +54,23 @@ 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( + 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( + chalk.yellow( + `⚠️ Warning! We'll be using the version associated with the \`--${ + opts.token ? 'token' : 'id' + }\` option, so the \`--version\` option will be ignored.` + ) + ); + } + if (!key) { return Promise.reject(new Error('No project API key provided. Please use `--key`.')); } 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); };