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.

Sign up for GitHub

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

docs(openapi): update working directory usage #453

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
413237a
chore: edit working directory copy
kanadgupta Feb 26, 2022
9cd4129
test: update tests + snapshots
kanadgupta Feb 26, 2022
d3b2536
chore: tweak file title
kanadgupta Feb 26, 2022
f480c87
docs: add usage to README
kanadgupta Feb 26, 2022
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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion __tests__/__fixtures__/relative-ref-oas/petstore.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
{
Expand Down
36 changes: 18 additions & 18 deletions __tests__/__snapshots__/index.test.js.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand Down
4 changes: 2 additions & 2 deletions __tests__/cmds/__snapshots__/openapi.test.js.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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",
Expand Down
4 changes: 2 additions & 2 deletions __tests__/cmds/openapi.test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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')
Expand All @@ -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);

Expand Down
4 changes: 2 additions & 2 deletions __tests__/cmds/validate.test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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!'));
});
Expand Down
10 changes: 5 additions & 5 deletions src/cmds/openapi.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
10 changes: 5 additions & 5 deletions src/cmds/validate.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}`);
Expand Down