bump-cli 2.8.0 → 2.8.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -1
- package/lib/commands/deploy.js +1 -1
- package/lib/core/diff.d.ts +1 -0
- package/lib/core/diff.js +4 -2
- package/lib/core/overlay.js +20 -12
- package/oclif.manifest.json +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -87,7 +87,7 @@ $ bump --help
|
|
|
87
87
|
The Bump.sh CLI is used to interact with your API documentation hosted on Bump.sh by using the API of developers.bump.sh
|
|
88
88
|
|
|
89
89
|
VERSION
|
|
90
|
-
bump-cli/2.
|
|
90
|
+
bump-cli/2.8.0 linux-x64 node-v16.19.0
|
|
91
91
|
|
|
92
92
|
USAGE
|
|
93
93
|
$ bump [COMMAND]
|
|
@@ -96,6 +96,7 @@ COMMANDS
|
|
|
96
96
|
deploy Create a new version of your documentation from the given file or URL.
|
|
97
97
|
diff Get a comparison diff with your documentation from the given file or URL.
|
|
98
98
|
help Display help for bump.
|
|
99
|
+
overlay Apply an OpenAPI specified overlay to your API definition.
|
|
99
100
|
preview Create a documentation preview from the given file or URL.
|
|
100
101
|
```
|
|
101
102
|
|
|
@@ -112,6 +113,7 @@ Head over to your Documentation settings in the “CI deployment” section or y
|
|
|
112
113
|
* [`bump deploy [FILE]`](#bump-deploy-file)
|
|
113
114
|
* [`bump diff [FILE]`](#bump-diff-file)
|
|
114
115
|
* [`bump preview [FILE]`](#bump-preview-file)
|
|
116
|
+
* [`bump overlay [DEFINITION_FILE] [OVERLAY_FILE]`](#bump-overlay-definition_file-overlay_file)
|
|
115
117
|
|
|
116
118
|
### `bump deploy [FILE]`
|
|
117
119
|
|
|
@@ -245,6 +247,26 @@ _Note: the additional `--open` flag helps to automatically open the preview URL
|
|
|
245
247
|
|
|
246
248
|
Please check `bump preview --help` for more usage details
|
|
247
249
|
|
|
250
|
+
### `bump overlay [DEFINITION_FILE] [OVERLAY_FILE]`
|
|
251
|
+
|
|
252
|
+
> This feature implements the [OpenAPI Overlay specification](https://github.com/OAI/Overlay-Specification). It is possible to apply an Overlay to any kind of document, be it an OpenAPI or AsyncAPI definition file.
|
|
253
|
+
|
|
254
|
+
The Overlay specification of OpenAPI makes it possible to modify the content of an API definition file by adding a layer on top of it. That layer helps adding, removing or changing some or all of the content of the original definition.
|
|
255
|
+
|
|
256
|
+
Technically, the `bump overlay` command will output a modified version of the `[DEFINITION_FILE]` (an OpenAPI or AsyncAPI document) by applying the operations described in the `[OVERLAY_FILE]` Overlay file to the original API document.
|
|
257
|
+
|
|
258
|
+
To redirect the output of the command to a new file you can run:
|
|
259
|
+
|
|
260
|
+
```shell
|
|
261
|
+
bump overlay api-document.yaml overlay-file.yaml > api-overlayed-document.yaml
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
_Note: you can also apply the overlay during the [`bump deploy` command]((#bump-deploy-file)) with the new `--overlay` flag:_
|
|
265
|
+
|
|
266
|
+
```shell
|
|
267
|
+
bump deploy api-document.yaml --doc my-doc --token my-token --overlay overlay-file.yaml
|
|
268
|
+
```
|
|
269
|
+
|
|
248
270
|
## Development
|
|
249
271
|
|
|
250
272
|
Make sure to have Node.js (At least v14) installed on your machine.
|
package/lib/commands/deploy.js
CHANGED
|
@@ -87,7 +87,7 @@ class Deploy extends command_1.default {
|
|
|
87
87
|
});
|
|
88
88
|
}
|
|
89
89
|
else {
|
|
90
|
-
throw new errors_2.CLIError(`No
|
|
90
|
+
throw new errors_2.CLIError(`No documentation found in ${dir} with the pattern '${filenamePattern}'.\nYou should check with the ${chalk_1.default.dim('--filename-pattern')} flag to select your files from your naming convention.\nIf you don't have a naming convention we can help naming your API definition files:\nTry the ${chalk_1.default.dim('--interactive')} flag for that.`);
|
|
91
91
|
}
|
|
92
92
|
return;
|
|
93
93
|
}
|
package/lib/core/diff.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ import * as Config from '@oclif/config';
|
|
|
2
2
|
import { BumpApi } from '../api';
|
|
3
3
|
import { VersionResponse, WithDiff, DiffResponse } from '../api/models';
|
|
4
4
|
export declare class Diff {
|
|
5
|
+
static readonly TIMEOUT = 120;
|
|
5
6
|
_bump: BumpApi;
|
|
6
7
|
_config: Config.IConfig;
|
|
7
8
|
constructor(config: Config.IConfig);
|
package/lib/core/diff.js
CHANGED
|
@@ -26,7 +26,7 @@ class Diff {
|
|
|
26
26
|
}
|
|
27
27
|
if (diffVersion) {
|
|
28
28
|
return await this.waitResult(diffVersion, token, {
|
|
29
|
-
timeout:
|
|
29
|
+
timeout: Diff.TIMEOUT,
|
|
30
30
|
format,
|
|
31
31
|
});
|
|
32
32
|
}
|
|
@@ -98,7 +98,7 @@ class Diff {
|
|
|
98
98
|
pollingResponse = await this.bumpClient.getDiff(result.id, opts.format);
|
|
99
99
|
}
|
|
100
100
|
if (opts.timeout <= 0) {
|
|
101
|
-
throw new errors_1.CLIError('We were unable to compute your documentation diff. Sorry about that. Please try again later');
|
|
101
|
+
throw new errors_1.CLIError('We were unable to compute your documentation diff. Sorry about that. Please try again later. If the error persists, please contact support at https://bump.sh.');
|
|
102
102
|
}
|
|
103
103
|
switch (pollingResponse.status) {
|
|
104
104
|
case 200:
|
|
@@ -152,3 +152,5 @@ class Diff {
|
|
|
152
152
|
}
|
|
153
153
|
}
|
|
154
154
|
exports.Diff = Diff;
|
|
155
|
+
// 120 seconds = 2 minutes
|
|
156
|
+
Diff.TIMEOUT = 120;
|
package/lib/core/overlay.js
CHANGED
|
@@ -44,21 +44,29 @@ class Overlay {
|
|
|
44
44
|
else {
|
|
45
45
|
try {
|
|
46
46
|
// It must be an update
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
47
|
+
// Deep merge objects using a module (built-in spread operator is only shallow)
|
|
48
|
+
const merger = (0, mergician_1.default)({ appendArrays: true });
|
|
49
|
+
if (target === '$') {
|
|
50
|
+
// You can't actually merge an update on a root object
|
|
51
|
+
// target with the jsonpath lib, this is just us merging
|
|
52
|
+
// the given update with the whole spec.
|
|
53
|
+
spec = merger(spec, action.update);
|
|
54
|
+
}
|
|
55
|
+
else {
|
|
56
|
+
jsonpath_1.default.apply(spec, target, (chunk) => {
|
|
57
|
+
if (typeof chunk === 'object' && typeof action.update === 'object') {
|
|
58
|
+
if (Array.isArray(chunk) && Array.isArray(action.update)) {
|
|
59
|
+
return chunk.concat(action.update);
|
|
60
|
+
}
|
|
61
|
+
else {
|
|
62
|
+
return merger(chunk, action.update);
|
|
63
|
+
}
|
|
51
64
|
}
|
|
52
65
|
else {
|
|
53
|
-
|
|
54
|
-
const merger = (0, mergician_1.default)({ appendArrays: true });
|
|
55
|
-
return merger(chunk, action.update);
|
|
66
|
+
return action.update;
|
|
56
67
|
}
|
|
57
|
-
}
|
|
58
|
-
|
|
59
|
-
return action.update;
|
|
60
|
-
}
|
|
61
|
-
});
|
|
68
|
+
});
|
|
69
|
+
}
|
|
62
70
|
}
|
|
63
71
|
catch (ex) {
|
|
64
72
|
process.stderr.write(`Error applying overlay: ${ex.message}\n`);
|
package/oclif.manifest.json
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":"2.8.
|
|
1
|
+
{"version":"2.8.1","commands":{"deploy":{"id":"deploy","description":"Create a new version of your documentation from the given file or URL.","pluginName":"bump-cli","pluginType":"core","aliases":[],"examples":["Deploy a new version of an existing documentation\n\n$ bump deploy FILE --doc <your_doc_id_or_slug> --token <your_doc_token>\n* Let's deploy a new documentation version on Bump... done\n* Your new documentation version will soon be ready\n","Deploy a new version of an existing documentation attached to a hub\n\n$ bump deploy FILE --doc <doc_slug> --hub <your_hub_id_or_slug> --token <your_doc_token>\n* Let's deploy a new documentation version on Bump... done\n* Your new documentation version will soon be ready\n","Deploy a whole directory of API definitions files to a hub\n\n$ bump deploy DIR --filename-pattern *-{slug}-api --hub <hub_slug> --token <hub_token>\nWe've found 2 valid API definitions to deploy\n└─ DIR\n └─ source-my-service-api.yml (OpenAPI spec version 3.1.0)\n └─ source-my-jobs-service-api.yml (AsyncAPI spec version 2.6.0)\n\nLet's deploy those documentations to your <hub_slug> hub on Bump.sh\n\n* Your new documentation version will soon be ready\nLet's deploy a new version to your my-service documentation on Bump.sh... done\n\n* Your new documentation version will soon be ready\nLet's deploy a new version to your my-jobs-service documentation on Bump.sh... done\n","Validate a new documentation version before deploying it\n\n$ bump deploy FILE --dry-run --doc <doc_slug> --token <your_doc_token>\n* Let's validate a new documentation version on Bump... done\n* Definition is valid\n"],"flags":{"help":{"name":"help","type":"boolean","char":"h","description":"show CLI help","allowNo":false},"doc":{"name":"doc","type":"option","char":"d","description":"Documentation public id or slug. Can be provided via BUMP_ID environment variable"},"doc-name":{"name":"doc-name","type":"option","char":"n","description":"Documentation name. Used with --auto-create flag."},"hub":{"name":"hub","type":"option","char":"b","description":"Hub id or slug. Can be provided via BUMP_HUB_ID environment variable"},"branch":{"name":"branch","type":"option","char":"B","description":"Branch name. Can be provided via BUMP_BRANCH_NAME environment variable"},"token":{"name":"token","type":"option","char":"t","description":"Documentation or Hub token. Can be provided via BUMP_TOKEN environment variable","required":true},"auto-create":{"name":"auto-create","type":"boolean","description":"Automatically create the documentation if needed (only available with a --hub flag). Documentation name can be provided with --doc-name flag. Default: false","allowNo":false},"interactive":{"name":"interactive","type":"boolean","description":"Interactively create a configuration file to deploy a Hub (only available with a --hub flag). This will start an interactive process if you don't have a CLI configuration file. Default: false","allowNo":false},"filename-pattern":{"name":"filename-pattern","type":"option","description":"Pattern to extract the documentation slug from filenames when deploying a DIRECTORY. Pattern uses only '*' and '{slug}' as special characters to extract the slug from a filename without extension. Used with --hub flag only.","default":"{slug}-api"},"dry-run":{"name":"dry-run","type":"boolean","description":"Validate a new documentation version. Does everything a normal deploy would do except publishing the new version. Useful in automated environments such as test platforms or continuous integration. Default: false","allowNo":false},"overlay":{"name":"overlay","type":"option","char":"o","description":"Path or URL of an overlay file to apply before deploying"}},"args":[{"name":"FILE","description":"Path or URL to your API documentation file. OpenAPI (2.0 to 3.1.0) and AsyncAPI (2.x) specifications are currently supported.\nPath can also be a directory when deploying to a Hub.","required":true}]},"diff":{"id":"diff","description":"Get a comparison diff with your documentation from the given file or URL.","pluginName":"bump-cli","pluginType":"core","aliases":[],"examples":["Compare a potential new version with the currently published one:\n\n $ bump diff FILE --doc <your_doc_id_or_slug> --token <your_doc_token>\n * Comparing the given definition file with the currently deployed one... done\n Removed: GET /compare\n Added: GET /versions/{versionId}\n","Store the diff in a dedicated file:\n\n $ bump diff FILE --doc <doc_slug> --token <doc_token> > /tmp/my-saved-diff\n * Comparing the given definition file with the currently deployed one... done\n\n $ cat /tmp/my-saved-diff\n Removed: GET /compare\n Added: GET /versions/{versionId}\n","In case of a non modified definition FILE compared to your existing documentation, no changes are output:\n\n $ bump diff FILE --doc <doc_slug> --token <your_doc_token>\n * Comparing the given definition file with the currently deployed one... done\n › Warning: Your documentation has not changed\n","Compare two different input files or URL independently to the one published on bump.sh\n\n $ bump diff FILE FILE2 --doc <doc_slug> --token <your_doc_token>\n * Comparing the two given definition files... done\n Updated: POST /versions\n Body attribute added: previous_version_id\n"],"flags":{"help":{"name":"help","type":"boolean","char":"h","description":"show CLI help","allowNo":false},"doc":{"name":"doc","type":"option","char":"d","description":"Documentation public id or slug. Can be provided via BUMP_ID environment variable"},"hub":{"name":"hub","type":"option","char":"b","description":"Hub id or slug. Can be provided via BUMP_HUB_ID environment variable"},"branch":{"name":"branch","type":"option","char":"B","description":"Branch name. Can be provided via BUMP_BRANCH_NAME environment variable"},"token":{"name":"token","type":"option","char":"t","description":"Documentation or Hub token. Can be provided via BUMP_TOKEN environment variable","required":false},"open":{"name":"open","type":"boolean","char":"o","description":"Open the visual diff in your browser","allowNo":false},"fail-on-breaking":{"name":"fail-on-breaking","type":"boolean","char":"F","description":"Fail when diff contains a breaking change","allowNo":false},"format":{"name":"format","type":"option","char":"f","description":"Format in which to provide the diff result","options":["text","markdown","json","html"],"default":"text"},"expires":{"name":"expires","type":"option","char":"e","description":"Specify a longer expiration date for public diffs (defaults to 1 day). Use iso8601 format to provide a date, or you can use `--expires 'never'` to keep the result live indefinitely."}},"args":[{"name":"FILE","description":"Path or URL to your API documentation file. OpenAPI (2.0 to 3.1.0) and AsyncAPI (2.x) specifications are currently supported.\nPath can also be a directory when deploying to a Hub.","required":true},{"name":"FILE2","description":"Path or URL to a second API documentation file to compute its diff"}]},"overlay":{"id":"overlay","description":"Apply an OpenAPI specified overlay to your API definition.","pluginName":"bump-cli","pluginType":"core","aliases":[],"examples":["Apply the OVERLAY_FILE to the existing DEFINITION_FILE. The resulting\ndefinition is output on stdout meaning you can redirect it to a new\nfile.\n\n$ bump overlay DEFINITION_FILE OVERLAY_FILE > destination/file.json\n* Let's apply the overlay to the main definition... done\n"],"flags":{"help":{"name":"help","type":"boolean","char":"h","description":"show CLI help","allowNo":false},"out":{"name":"out","type":"option","char":"o","description":"Output file path"}},"args":[{"name":"FILE","description":"Path or URL to your API documentation file. OpenAPI (2.0 to 3.1.0) and AsyncAPI (2.x) specifications are currently supported.\nPath can also be a directory when deploying to a Hub.","required":true},{"name":"OVERLAY_FILE","description":"Path or URL to an overlay file","required":true}]},"preview":{"id":"preview","description":"Create a documentation preview from the given file or URL.","pluginName":"bump-cli","pluginType":"core","aliases":[],"examples":["$ bump preview FILE\n* Your preview is visible at: https://bump.sh/preview/45807371-9a32-48a7-b6e4-1cb7088b5b9b\n"],"flags":{"help":{"name":"help","type":"boolean","char":"h","description":"show CLI help","allowNo":false},"live":{"name":"live","type":"boolean","char":"l","description":"Generate a preview each time you save the given file","allowNo":false},"open":{"name":"open","type":"boolean","char":"o","description":"Open the generated preview URL in your browser","allowNo":false}},"args":[{"name":"FILE","description":"Path or URL to your API documentation file. OpenAPI (2.0 to 3.1.0) and AsyncAPI (2.x) specifications are currently supported.\nPath can also be a directory when deploying to a Hub.","required":true}]}}}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "bump-cli",
|
|
3
3
|
"description": "The Bump CLI is used to interact with your API documentation hosted on Bump by using the API of developers.bump.sh",
|
|
4
|
-
"version": "2.8.
|
|
4
|
+
"version": "2.8.1",
|
|
5
5
|
"author": "Paul Bonaud <paulr@bump.sh>",
|
|
6
6
|
"bin": {
|
|
7
7
|
"bump": "./bin/run"
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
"globby": "^11.0.3",
|
|
25
25
|
"mocha": "^10.0.0",
|
|
26
26
|
"nock": "^13.0.11",
|
|
27
|
-
"np": "^
|
|
27
|
+
"np": "^10.0.5",
|
|
28
28
|
"nyc": "^15.1.0",
|
|
29
29
|
"prettier": "^2.2.1",
|
|
30
30
|
"sinon": "^14.0.0",
|
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
"typescript": "4.5.5"
|
|
34
34
|
},
|
|
35
35
|
"engines": {
|
|
36
|
-
"node": ">=
|
|
36
|
+
"node": ">=16.0.0"
|
|
37
37
|
},
|
|
38
38
|
"files": [
|
|
39
39
|
"/bin",
|