From e1745bcb3621bc8c917df3806b62c75b11546ae6 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Sun, 27 Feb 2022 20:58:35 -0600 Subject: [PATCH] docs(openapi): update working directory usage (#453) * chore: edit working directory copy * test: update tests + snapshots * chore: tweak file title * docs: add usage to README --- README.md | 8 +++++ .../relative-ref-oas/petstore.json | 2 +- __tests__/__snapshots__/index.test.js.snap | 36 +++++++++---------- .../cmds/__snapshots__/openapi.test.js.snap | 4 +-- __tests__/cmds/openapi.test.js | 4 +-- __tests__/cmds/validate.test.js | 4 +-- src/cmds/openapi.js | 10 +++--- src/cmds/validate.js | 10 +++--- 8 files changed, 43 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index cb10c2b8e..90f1b56e2 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,14 @@ If you run `rdme` within a directory that contains your OpenAPI or Swagger defin rdme openapi ``` +#### Override the Working Directory + +By default, `rdme` bundles all [references](https://swagger.io/docs/specification/using-ref/) with paths based on the directory that `rdme` is being run in. You can override the working directory using the `--workingDirectory` option, which can be helpful for bundling certain external references (see [here](__tests__/__fixtures__/relative-ref-oas/petstore.json) for an example file). + +```sh +rdme openapi petstore.json --workingDirectory=[path to directory] +``` + #### Validating an API Definition 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. diff --git a/__tests__/__fixtures__/relative-ref-oas/petstore.json b/__tests__/__fixtures__/relative-ref-oas/petstore.json index a060f83f6..cd8d05f12 100644 --- a/__tests__/__fixtures__/relative-ref-oas/petstore.json +++ b/__tests__/__fixtures__/relative-ref-oas/petstore.json @@ -2,7 +2,7 @@ "openapi": "3.0.0", "info": { "version": "1.0.0", - "title": "Example petstore to demo our handling of external $ref pointers" + "title": "Example petstore to demo our handling of relative external $ref pointers" }, "servers": [ { diff --git a/__tests__/__snapshots__/index.test.js.snap b/__tests__/__snapshots__/index.test.js.snap index cde9d198f..f661d37f2 100644 --- a/__tests__/__snapshots__/index.test.js.snap +++ b/__tests__/__snapshots__/index.test.js.snap @@ -10,12 +10,12 @@ Usage Options - --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 - --workdir string Directory as working directory - -h, --help Display this usage guide + --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 + --workingDirectory string Working directory (for usage with relative external references) + -h, --help Display this usage guide Related commands @@ -180,12 +180,12 @@ Usage Options - --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 - --workdir string Directory as working directory - -h, --help Display this usage guide + --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 + --workingDirectory string Working directory (for usage with relative external references) + -h, --help Display this usage guide Related commands @@ -204,12 +204,12 @@ Usage Options - --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 - --workdir string Directory as working directory - -h, --help Display this usage guide + --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 + --workingDirectory string Working directory (for usage with relative external references) + -h, --help Display this usage guide Related commands diff --git a/__tests__/cmds/__snapshots__/openapi.test.js.snap b/__tests__/cmds/__snapshots__/openapi.test.js.snap index 2f7ebc6ac..d298cc141 100644 --- a/__tests__/cmds/__snapshots__/openapi.test.js.snap +++ b/__tests__/cmds/__snapshots__/openapi.test.js.snap @@ -250,7 +250,7 @@ Object { } `; -exports[`rdme openapi should use specified workdir and upload the expected content 1`] = ` +exports[`rdme openapi should use specified working directory and upload the expected content 1`] = ` Object { "components": Object { "securitySchemes": Object { @@ -274,7 +274,7 @@ Object { }, }, "info": Object { - "title": "Example petstore to demo our handling of external $ref pointers", + "title": "Example petstore to demo our handling of relative external $ref pointers", "version": "1.0.0", }, "openapi": "3.0.0", diff --git a/__tests__/cmds/openapi.test.js b/__tests__/cmds/openapi.test.js index b959d9951..1b837d94a 100644 --- a/__tests__/cmds/openapi.test.js +++ b/__tests__/cmds/openapi.test.js @@ -286,7 +286,7 @@ describe('rdme openapi', () => { return mock.done(); }); - it('should use specified workdir and upload the expected content', async () => { + it('should use specified working directory and upload the expected content', async () => { let requestBody = null; const mock = getApiNock() .get('/api/v1/api-specification') @@ -309,7 +309,7 @@ describe('rdme openapi', () => { spec: 'petstore.json', key, version, - workdir: './__tests__/__fixtures__/relative-ref-oas', + workingDirectory: './__tests__/__fixtures__/relative-ref-oas', }) ).resolves.toBe(successfulUpload); diff --git a/__tests__/cmds/validate.test.js b/__tests__/cmds/validate.test.js index fc53bd6ed..1637ed72d 100644 --- a/__tests__/cmds/validate.test.js +++ b/__tests__/cmds/validate.test.js @@ -55,11 +55,11 @@ describe('rdme validate', () => { fs.unlinkSync('./swagger.json'); }); - it('should use specified workdir', async () => { + it('should use specified working directory', async () => { await expect( validate.run({ spec: 'petstore.json', - workdir: './__tests__/__fixtures__/relative-ref-oas', + workingDirectory: './__tests__/__fixtures__/relative-ref-oas', }) ).resolves.toBe(chalk.green('petstore.json is a valid OpenAPI API definition!')); }); diff --git a/src/cmds/openapi.js b/src/cmds/openapi.js index a63cd8375..a6feb27c4 100644 --- a/src/cmds/openapi.js +++ b/src/cmds/openapi.js @@ -49,15 +49,15 @@ module.exports = class OpenAPICommand { defaultOption: true, }, { - name: 'workdir', + name: 'workingDirectory', type: String, - description: 'Directory as working directory', + description: 'Working directory (for usage with relative external references)', }, ]; } async run(opts) { - const { spec, version, workdir } = opts; + const { spec, version, workingDirectory } = opts; let { key, id } = opts; let selectedVersion; let isUpdate; @@ -65,8 +65,8 @@ module.exports = class OpenAPICommand { debug(`command: ${this.command}`); debug(`opts: ${JSON.stringify(opts)}`); - if (workdir) { - process.chdir(workdir); + if (workingDirectory) { + process.chdir(workingDirectory); } if (!key && opts.token) { diff --git a/src/cmds/validate.js b/src/cmds/validate.js index 3ee22d2a5..ff6fc2572 100644 --- a/src/cmds/validate.js +++ b/src/cmds/validate.js @@ -19,18 +19,18 @@ module.exports = class ValidateCommand { defaultOption: true, }, { - name: 'workdir', + name: 'workingDirectory', type: String, - description: 'Directory as working directory', + description: 'Working directory (for usage with relative external references)', }, ]; } async run(opts) { - const { spec, workdir } = opts; + const { spec, workingDirectory } = opts; - if (workdir) { - process.chdir(workdir); + if (workingDirectory) { + process.chdir(workingDirectory); } debug(`command: ${this.command}`);