Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(openapi): update working directory usage #453

Merged
merged 4 commits into from
Feb 28, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion __tests__/__fixtures__/relative-ref-oas/petstore.json
Original file line number Diff line number Diff line change
@@ -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": [
{
36 changes: 18 additions & 18 deletions __tests__/__snapshots__/index.test.js.snap
Original file line number Diff line number Diff line change
@@ -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

4 changes: 2 additions & 2 deletions __tests__/cmds/__snapshots__/openapi.test.js.snap
Original file line number Diff line number Diff line change
@@ -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",
4 changes: 2 additions & 2 deletions __tests__/cmds/openapi.test.js
Original file line number Diff line number Diff line change
@@ -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);

4 changes: 2 additions & 2 deletions __tests__/cmds/validate.test.js
Original file line number Diff line number Diff line change
@@ -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!'));
});
10 changes: 5 additions & 5 deletions src/cmds/openapi.js
Original file line number Diff line number Diff line change
@@ -49,24 +49,24 @@ 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;

debug(`command: ${this.command}`);
debug(`opts: ${JSON.stringify(opts)}`);

if (workdir) {
process.chdir(workdir);
if (workingDirectory) {
process.chdir(workingDirectory);
}

if (!key && opts.token) {
10 changes: 5 additions & 5 deletions src/cmds/validate.js
Original file line number Diff line number Diff line change
@@ -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}`);