bump-cli 2.8.1 → 2.8.4
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 +15 -9
- package/lib/commands/preview.js +1 -1
- package/lib/core/diff.js +2 -1
- package/lib/core/overlay.js +1 -1
- package/oclif.manifest.json +1 -1
- package/package.json +5 -7
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
|
|
12
12
|
The Bump.sh CLI is used to interact with your API documentation or hubs hosted on Bump.sh. With any API definition of your choice (from Swagger, OpenAPI or AsyncAPI), it can help you to:
|
|
13
13
|
|
|
14
|
-
- Validate an API document before publishing to your documentation
|
|
14
|
+
- Validate an API document before publishing it to your documentation
|
|
15
15
|
- Publish an API document to your Bump.sh documentation or hubs
|
|
16
16
|
- Compare two API documents to generate a human-readable diff from your API definitions
|
|
17
17
|
|
|
@@ -37,7 +37,7 @@ The Bump.sh CLI is a node package currently distributed via NPM. This means you
|
|
|
37
37
|
_If you are looking to use Bump.sh in a continuous integration environment you might be interested by [our Github Action](https://github.com/marketplace/actions/api-documentation-on-bump)._
|
|
38
38
|
|
|
39
39
|
> You can download a standalone package directly from the latest
|
|
40
|
-
>
|
|
40
|
+
> GitHub release assets if you don’t use Node.
|
|
41
41
|
{: .info}
|
|
42
42
|
|
|
43
43
|
### Global installation
|
|
@@ -56,7 +56,7 @@ yarn global add bump-cli
|
|
|
56
56
|
|
|
57
57
|
### Add Bump.sh to your node project
|
|
58
58
|
|
|
59
|
-
As our CLI is a node package, you can easily embed it
|
|
59
|
+
As our CLI is a node package, you can easily embed it into your project by adding the package to your `package.json` file, either with NPM
|
|
60
60
|
|
|
61
61
|
```sh-session
|
|
62
62
|
npm install --save-dev bump-cli
|
|
@@ -178,6 +178,12 @@ Please check `bump deploy --help` for more usage details.
|
|
|
178
178
|
|
|
179
179
|
_If you want to receive automatic `bump diff` results on your Github Pull Requests you might be interested by [our Github Action](https://github.com/marketplace/actions/api-documentation-on-bump#api-diff-on-pull-requests) diff command._
|
|
180
180
|
|
|
181
|
+
Please note that by default the command will always exit with a
|
|
182
|
+
successful return code. If you want to use this command in a CI
|
|
183
|
+
environment and want the command to fail **in case of a breaking
|
|
184
|
+
change**, you will need to add the `--fail-on-breaking` flag to your
|
|
185
|
+
diff command.
|
|
186
|
+
|
|
181
187
|
#### Public API diffs
|
|
182
188
|
|
|
183
189
|
From any two API documents or URLs, you can retrieve a comprehensive changelog of what has changed between them.
|
|
@@ -251,11 +257,11 @@ Please check `bump preview --help` for more usage details
|
|
|
251
257
|
|
|
252
258
|
> 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
259
|
|
|
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
|
|
260
|
+
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 add, remove, or change some or all of the content of the original definition.
|
|
255
261
|
|
|
256
262
|
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
263
|
|
|
258
|
-
To redirect the output of the command to a new file you can run:
|
|
264
|
+
To redirect the output of the command to a new file you can run the following:
|
|
259
265
|
|
|
260
266
|
```shell
|
|
261
267
|
bump overlay api-document.yaml overlay-file.yaml > api-overlayed-document.yaml
|
|
@@ -299,7 +305,7 @@ Make sure to have Node.js (At least v14) installed on your machine.
|
|
|
299
305
|
|
|
300
306
|
## Compatible specification types
|
|
301
307
|
|
|
302
|
-
We currently support [OpenAPI](https://github.com/OAI/OpenAPI-Specification) from 2.0 (called Swagger) to 3.1 and [AsyncAPI 2.x](https://www.asyncapi.com/docs/reference/specification/latest) specification file types. Both YAML
|
|
308
|
+
We currently support [OpenAPI](https://github.com/OAI/OpenAPI-Specification) from 2.0 (called Swagger) to 3.1 and [AsyncAPI 2.x](https://www.asyncapi.com/docs/reference/specification/latest) specification file types. Both YAML and JSON file formats are accepted file inputs to the CLI.
|
|
303
309
|
|
|
304
310
|
## Contributing
|
|
305
311
|
|
|
@@ -315,12 +321,12 @@ The Bump CLI project is released under the [MIT License](http://opensource.org/l
|
|
|
315
321
|
|
|
316
322
|
## Code of Conduct
|
|
317
323
|
|
|
318
|
-
Everyone interacting in the Bump-CLI project codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/bump-sh/.github/blob/main/CODE_OF_CONDUCT.md).
|
|
324
|
+
Everyone interacting in the Bump-CLI project codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/bump-sh/.github/blob/main/CODE_OF_CONDUCT.md).
|
|
319
325
|
|
|
320
326
|
## Versioning
|
|
321
327
|
|
|
322
328
|
This npm package starts at v2.0.0 for two main reasons:
|
|
323
329
|
|
|
324
|
-
- Our [first version](https://github.com/bump-sh/bump-cli) of the Bump CLI was written in Ruby, starting at v2.0.0 makes it clear we are working on our second version of the Bump CLI
|
|
330
|
+
- Our [first version](https://github.com/bump-sh/bump-cli) of the Bump CLI was written in Ruby, starting at v2.0.0, which makes it clear we are working on our second version of the Bump CLI
|
|
325
331
|
|
|
326
|
-
- The `bump-cli` package used to be [owned by Rico](https://github.com/rstacruz) which already published v1.x packages. If you are looking for the old npm package please head to [`@rstacruz/bump-cli` package](https://www.npmjs.com/package/@rstacruz/bump-cli). _A big thanks to Rico for
|
|
332
|
+
- The `bump-cli` package used to be [owned by Rico](https://github.com/rstacruz) which already published v1.x packages. If you are looking for the old npm package please head to [`@rstacruz/bump-cli` package](https://www.npmjs.com/package/@rstacruz/bump-cli). _A big thanks to Rico for transferring the ownership of the `bump-cli` package name!_
|
package/lib/commands/preview.js
CHANGED
|
@@ -22,7 +22,7 @@ class Preview extends command_1.default {
|
|
|
22
22
|
const [definition, references] = api.extractDefinition();
|
|
23
23
|
this.d(`${file} looks like an ${api.specName} spec version ${api.version}`);
|
|
24
24
|
if (!currentPreview) {
|
|
25
|
-
cli_1.cli.action.start("* Let's render a preview on Bump");
|
|
25
|
+
cli_1.cli.action.start("* Let's render a preview on Bump.sh");
|
|
26
26
|
}
|
|
27
27
|
const request = {
|
|
28
28
|
definition,
|
package/lib/core/diff.js
CHANGED
|
@@ -137,7 +137,8 @@ class Diff {
|
|
|
137
137
|
return result.doc_public_url !== undefined;
|
|
138
138
|
}
|
|
139
139
|
isVersionWithDiff(result) {
|
|
140
|
-
|
|
140
|
+
const { diff_summary, diff_markdown, diff_details } = result;
|
|
141
|
+
return (diff_summary || diff_markdown || diff_details) !== undefined;
|
|
141
142
|
}
|
|
142
143
|
extractDiff(versionWithDiff) {
|
|
143
144
|
// TODO: return a real diff_id in the GET /version API
|
package/lib/core/overlay.js
CHANGED
package/oclif.manifest.json
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":"2.8.
|
|
1
|
+
{"version":"2.8.4","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.4",
|
|
5
5
|
"author": "Paul Bonaud <paulr@bump.sh>",
|
|
6
6
|
"bin": {
|
|
7
7
|
"bump": "./bin/run"
|
|
@@ -56,8 +56,7 @@
|
|
|
56
56
|
"commands": "./lib/commands",
|
|
57
57
|
"bin": "bump",
|
|
58
58
|
"plugins": [
|
|
59
|
-
"@oclif/plugin-help"
|
|
60
|
-
"@oclif/plugin-warn-if-update-available"
|
|
59
|
+
"@oclif/plugin-help"
|
|
61
60
|
],
|
|
62
61
|
"warn-if-update-available": {
|
|
63
62
|
"timeoutInDays": 30,
|
|
@@ -85,14 +84,13 @@
|
|
|
85
84
|
"@apidevtools/json-schema-ref-parser": "^9.0.7",
|
|
86
85
|
"@asyncapi/specs": "^5.1.0",
|
|
87
86
|
"@clack/prompts": "^0.6.3",
|
|
88
|
-
"@oclif/command": "^1.8.
|
|
89
|
-
"@oclif/config": "^1.17
|
|
87
|
+
"@oclif/command": "^1.8.36",
|
|
88
|
+
"@oclif/config": "^1.18.17",
|
|
90
89
|
"@oclif/core": "1.20.4",
|
|
91
90
|
"@oclif/plugin-help": "^5.1.10",
|
|
92
|
-
"@oclif/plugin-warn-if-update-available": "^2.0.36",
|
|
93
91
|
"@stoplight/yaml": "^4.2.3",
|
|
94
92
|
"async-mutex": "^0.4.0",
|
|
95
|
-
"axios": "^
|
|
93
|
+
"axios": "^1.6.4",
|
|
96
94
|
"debug": "^4.3.1",
|
|
97
95
|
"jsonpath": "^1.1.1",
|
|
98
96
|
"mergician": "^1.0.3",
|