bump-cli 2.7.2 → 2.7.3-beta
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 +147 -68
- package/lib/args.d.ts +5 -1
- package/lib/args.js +6 -1
- package/lib/commands/overlay.d.ts +14 -0
- package/lib/commands/overlay.js +48 -0
- package/lib/commands/preview.d.ts +1 -1
- package/lib/commands/preview.js +6 -7
- package/lib/core/overlay.d.ts +2 -0
- package/lib/core/overlay.js +59 -0
- package/lib/definition.d.ts +9 -3
- package/lib/definition.js +9 -1
- package/lib/index.d.ts +2 -1
- package/lib/index.js +3 -1
- package/oclif.manifest.json +1 -1
- package/package.json +5 -1
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Bump
|
|
1
|
+
# Bump CLI
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
4
|
<img width="20%" src="https://bump.sh/icon-default-large.png" />
|
|
@@ -9,7 +9,13 @@
|
|
|
9
9
|
<a href="https://bump.sh/users/sign_up">Sign up</a>
|
|
10
10
|
</p>
|
|
11
11
|
|
|
12
|
-
The Bump CLI is used to interact with your API documentation hosted on Bump
|
|
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
|
+
|
|
14
|
+
- Validate an API document before publishing to your documentation
|
|
15
|
+
- Publish an API document to your Bump.sh documentation or hubs
|
|
16
|
+
- Compare two API documents to generate a human-readable diff from your API definitions
|
|
17
|
+
|
|
18
|
+
Under the hood, it uses the API of [developers.bump.sh](https://developers.bump.sh). And is built with the [`oclif`](https://oclif.io) framework in Typescript.
|
|
13
19
|
|
|
14
20
|
[](https://npmjs.org/package/bump-cli)
|
|
15
21
|
[](https://github.com/bump-sh/cli/actions/workflows/checks.yml)
|
|
@@ -26,28 +32,62 @@ The Bump CLI is used to interact with your API documentation hosted on Bump by u
|
|
|
26
32
|
|
|
27
33
|
## Installation
|
|
28
34
|
|
|
29
|
-
Bump is
|
|
35
|
+
The Bump.sh CLI is a node package currently distributed via NPM. This means you must have the Node v14+ interpreter installed on your computer or CI servers.
|
|
36
|
+
|
|
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
|
+
|
|
39
|
+
> You can download a standalone package directly from the latest
|
|
40
|
+
> Github release assets if you don’t use Node.
|
|
41
|
+
{: .info}
|
|
42
|
+
|
|
43
|
+
### Global installation
|
|
44
|
+
|
|
45
|
+
To install it globally, run the following command with NPM
|
|
30
46
|
|
|
31
47
|
```sh-session
|
|
32
48
|
npm install -g bump-cli
|
|
33
49
|
```
|
|
34
50
|
|
|
35
|
-
|
|
51
|
+
Or, with Yarn via
|
|
52
|
+
|
|
53
|
+
```sh-session
|
|
54
|
+
yarn global add bump-cli
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### Add Bump.sh to your node project
|
|
58
|
+
|
|
59
|
+
As our CLI is a node package, you can easily embed it to your project by adding the package to your `package.json` file, either with NPM
|
|
60
|
+
|
|
61
|
+
```sh-session
|
|
62
|
+
npm install --save-dev bump-cli
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Or with Yarn via
|
|
66
|
+
|
|
67
|
+
```sh-session
|
|
68
|
+
yarn add --dev bump-cli
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
You can then use any Bump.sh commands with `npx` (same as `npm exec`)
|
|
72
|
+
|
|
73
|
+
```sh-session
|
|
74
|
+
npx bump --help
|
|
75
|
+
```
|
|
36
76
|
|
|
37
77
|
### How should I do if I'm not using npm ?
|
|
38
78
|
|
|
39
|
-
Unfortunately, at the moment we only
|
|
79
|
+
Unfortunately, at the moment we only support the Node environment. However, you can download a standalone package directly from the [latest Github release](https://github.com/bump-sh/cli/releases) assets which you can run as a standalone binary. Or you can push your documentation using [our API](https://developers.bump.sh/) (advanced usage only).
|
|
40
80
|
|
|
41
81
|
## Usage
|
|
42
82
|
|
|
43
|
-
|
|
44
|
-
$ npm install -g bump-cli
|
|
83
|
+
To list all the available commands, just type `bump` in your command line environment.
|
|
45
84
|
|
|
85
|
+
```sh-session
|
|
46
86
|
$ bump --help
|
|
47
|
-
The Bump CLI is used to interact with your API documentation hosted on Bump by using the API of developers.bump.sh
|
|
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
|
|
48
88
|
|
|
49
89
|
VERSION
|
|
50
|
-
bump-cli/2.
|
|
90
|
+
bump-cli/2.7.2 linux-x64 node-v16.17.0
|
|
51
91
|
|
|
52
92
|
USAGE
|
|
53
93
|
$ bump [COMMAND]
|
|
@@ -59,64 +99,78 @@ COMMANDS
|
|
|
59
99
|
preview Create a documentation preview from the given file or URL.
|
|
60
100
|
```
|
|
61
101
|
|
|
62
|
-
|
|
102
|
+
You can also get some help anytime by adding `--help` to any command. Example: `bump deploy --help`.
|
|
103
|
+
|
|
104
|
+
## Prepare your Bump.sh account
|
|
105
|
+
|
|
106
|
+
While some commands don't need any API token (`preview` or `diff`) you will need an access key if you want to interact with your Bump.sh documentation.
|
|
107
|
+
|
|
108
|
+
Head over to your Documentation settings in the “CI deployment” section or your Account or Organization settings in the “API keys” section to fetch a personal token for later usage.
|
|
63
109
|
|
|
64
110
|
## Commands
|
|
65
111
|
|
|
66
|
-
* [`bump preview [FILE]`](#bump-preview-file)
|
|
67
112
|
* [`bump deploy [FILE]`](#bump-deploy-file)
|
|
68
113
|
* [`bump diff [FILE]`](#bump-diff-file)
|
|
114
|
+
* [`bump preview [FILE]`](#bump-preview-file)
|
|
69
115
|
|
|
70
|
-
### `bump
|
|
71
|
-
|
|
72
|
-
You can preview your documentation by calling the `preview` command. A temporary preview will be created with a unique URL. This preview will be available for 30 minutes. You don't need any credentials to use this command. Here is an example usage:
|
|
116
|
+
### `bump deploy [FILE]`
|
|
73
117
|
|
|
118
|
+
When you update your API, you also want its documentation to be up to date for your API users. This is what the deploy command is for.
|
|
74
119
|
|
|
75
120
|
```sh-session
|
|
76
|
-
|
|
77
|
-
* Let's render a preview on Bump... done
|
|
78
|
-
* Your preview is visible at: https://bump.sh/preview/c192dad0-79d7-44b3-b5e1-244b69f618e4 (Expires at 2021-06-28T18:06:56+02:00)
|
|
121
|
+
bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN
|
|
79
122
|
```
|
|
80
123
|
|
|
81
|
-
|
|
124
|
+
> You can find your own `my-documentation` slug and `$DOC_TOKEN` api key from your [documentation settings](https://bump.sh/docs).
|
|
125
|
+
{: .info}
|
|
82
126
|
|
|
83
|
-
|
|
127
|
+
You can also deploy a given API document to a different branch of your documentation with the `--branch <branch-name>` parameter. Please note the branch will be created if it doesn’t exist. More details about the branching feature are available on [this dedicated help page](https://docs.bump.sh/help/branching). E.g. deploy the API document to the `staging` branch of the documentation:
|
|
84
128
|
|
|
85
|
-
|
|
129
|
+
```sh-session
|
|
130
|
+
bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN --branch staging
|
|
131
|
+
```
|
|
86
132
|
|
|
87
|
-
|
|
133
|
+
#### Deploy a folder all at once
|
|
88
134
|
|
|
89
|
-
|
|
135
|
+
If you already have a hub in your [Bump.sh](https://bump.sh) account, you can automatically create documentation and deploy it into that hub by publishing a whole directory containing multiple API documents in a single command:
|
|
90
136
|
|
|
91
137
|
```sh-session
|
|
92
|
-
|
|
138
|
+
bump deploy dir/path/to/apis/ --auto-create --hub my-hub --token $HUB_TOKEN
|
|
93
139
|
```
|
|
94
140
|
|
|
95
|
-
|
|
141
|
+
> You can find your own `my-hub` slug and `$HUB_TOKEN` api key from your [hub settings](https://bump.sh/hubs).
|
|
142
|
+
{: .info}
|
|
96
143
|
|
|
97
|
-
|
|
98
|
-
$ bump deploy path/to/your/file.yml --doc DOC_ID_OR_SLUG --token DOC_TOKEN --branch staging
|
|
99
|
-
```
|
|
144
|
+
Please note, by default, only files named `{slug}-api.[format]` are published. Where `{slug}` is a name for your API and `[format]` is either `yaml` or `json`. Adjust to your file naming convention using the `--filename-pattern <pattern>` option.
|
|
100
145
|
|
|
101
|
-
|
|
146
|
+
Note that it _can_ include `*` wildcard special character, but **must** include the `{slug}` filter to extract your documentation’s slug from the filename. The pattern can also have any other optional fixed characters.
|
|
102
147
|
|
|
103
|
-
|
|
104
|
-
|
|
148
|
+
Here’s a practical example. Let's assume that you have the following files in your `path/to/apis/` directory:
|
|
149
|
+
|
|
150
|
+
```
|
|
151
|
+
path/to/apis
|
|
152
|
+
└─ private-api-users-service.json
|
|
153
|
+
└─ partner-api-payments-service.yml
|
|
154
|
+
└─ public-api-contracts-service.yml
|
|
155
|
+
└─ data.json
|
|
156
|
+
└─ README.md
|
|
105
157
|
```
|
|
106
158
|
|
|
107
|
-
|
|
159
|
+
In order to deploy the 3 services API definition files from this folder (`private-api-users-service.json`, `partner-api-payments-service.yml` and `public-api-contracts-service.yml`), you can execute the following command:
|
|
108
160
|
|
|
109
|
-
```
|
|
110
|
-
|
|
161
|
+
```
|
|
162
|
+
bump deploy path/to/apis/ --hub my-hub --filename-pattern '*-api-{slug}-service'
|
|
111
163
|
```
|
|
112
164
|
|
|
113
|
-
|
|
165
|
+
#### Validate an API document
|
|
166
|
+
|
|
167
|
+
Simulate your API document's deployment to ensure it is valid by adding the `--dry-run` flag to the `deploy` command. It is handy in a Continuous Integration environment running a test deployment outside your main branch:
|
|
114
168
|
|
|
115
169
|
```sh-session
|
|
116
|
-
|
|
170
|
+
bump deploy path/to/api-document.yml --dry-run --doc my-documentation --token $DOC_TOKEN
|
|
117
171
|
```
|
|
118
172
|
|
|
119
|
-
Please check `bump deploy --help` for more usage details
|
|
173
|
+
Please check `bump deploy --help` for more usage details.
|
|
120
174
|
|
|
121
175
|
### `bump diff [FILE]`
|
|
122
176
|
|
|
@@ -124,7 +178,7 @@ _If you want to receive automatic `bump diff` results on your Github Pull Reques
|
|
|
124
178
|
|
|
125
179
|
#### Public API diffs
|
|
126
180
|
|
|
127
|
-
From any two
|
|
181
|
+
From any two API documents or URLs, you can retrieve a comprehensive changelog of what has changed between them.
|
|
128
182
|
|
|
129
183
|
```sh-session
|
|
130
184
|
$ bump diff path/to/your/file.yml path/to/your/second_file.yml
|
|
@@ -133,42 +187,63 @@ Modified: GET /consommations
|
|
|
133
187
|
Response modified: 200
|
|
134
188
|
[Breaking] Body attribute modified: energie
|
|
135
189
|
```
|
|
190
|
+
> You can create as many diffs as you like without being authenticated. This is a **free and unlimited service** provided as long as you use the service fairly.
|
|
191
|
+
{: .info}
|
|
192
|
+
|
|
193
|
+
_Note: You can also test this feature in our dedicated web application at <https://api-diff.io/>._
|
|
194
|
+
|
|
195
|
+
#### Authenticated diffs related to your Bump.sh documentation
|
|
136
196
|
|
|
137
|
-
|
|
197
|
+
From an existing Bump.sh documentation, the `diff` command will retrieve a comparison changelog between your latest published documentation and the given file or URL:
|
|
138
198
|
|
|
139
199
|
```sh-session
|
|
140
|
-
|
|
141
|
-
* Comparing the two given definition files... done
|
|
142
|
-
Modified: POST /books
|
|
143
|
-
Response modified: 200
|
|
144
|
-
[Breaking] Body attribute removed: cent
|
|
200
|
+
bump diff path/to/your/file.yml --doc my-documentation --token $DOC_TOKEN
|
|
145
201
|
```
|
|
146
202
|
|
|
147
|
-
|
|
203
|
+
If you want to compare two unpublished versions of your API document, the `diff` command can retrieve a comparison changelog between two given file or URL, “as simple as `git diff`”:
|
|
148
204
|
|
|
149
|
-
|
|
205
|
+
```sh-session
|
|
206
|
+
bump diff path/to/your/file.yml path/to/your/next-file.yml --doc my-documentation --token $DOC_TOKEN
|
|
207
|
+
```
|
|
150
208
|
|
|
151
|
-
|
|
209
|
+
Please check `bump diff --help` for full usage details.
|
|
152
210
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
211
|
+
### `bump preview [FILE]`
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
When writing documentation, you might want to preview how it renders on Bump.sh. This is precisely the goal of the `preview` command: it will create temporary documentation with a unique URL, which will be available for a short period (30 minutes).
|
|
156
215
|
|
|
157
|
-
|
|
158
|
-
|
|
216
|
+
Usage from a local OpenAPI or AsyncAPI file
|
|
217
|
+
|
|
218
|
+
```shell
|
|
219
|
+
bump preview path/to/file.json
|
|
159
220
|
```
|
|
160
221
|
|
|
161
|
-
|
|
222
|
+
You can also preview a file available from a URL
|
|
162
223
|
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
|
|
224
|
+
```shell
|
|
225
|
+
bump preview https://developers.bump.sh/source.yaml
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
#### Live preview
|
|
229
|
+
|
|
230
|
+
By using the `--live` flag you can stay focused on API design (OpenAPI or AsyncAPI file) while seeing a continuously updated preview each time you save your API document.
|
|
166
231
|
|
|
167
|
-
|
|
168
|
-
|
|
232
|
+
- Launch the live preview command in your terminal
|
|
233
|
+
|
|
234
|
+
```shell
|
|
235
|
+
bump preview --live --open openapi-definition.json
|
|
169
236
|
```
|
|
170
237
|
|
|
171
|
-
|
|
238
|
+
- Edit your `openapi-definition.json` file in your favorite text editor
|
|
239
|
+
- Watch the live preview being updated each time you save your file.
|
|
240
|
+
|
|
241
|
+
> You can create as many previews as you like without being authenticated. This is a **free and unlimited service**.
|
|
242
|
+
{: .info}
|
|
243
|
+
|
|
244
|
+
_Note: the additional `--open` flag helps to automatically open the preview URL in your browser._
|
|
245
|
+
|
|
246
|
+
Please check `bump preview --help` for more usage details
|
|
172
247
|
|
|
173
248
|
## Development
|
|
174
249
|
|
|
@@ -177,38 +252,42 @@ Make sure to have Node.js (At least v14) installed on your machine.
|
|
|
177
252
|
- Install node dependencies with
|
|
178
253
|
|
|
179
254
|
```sh-session
|
|
180
|
-
|
|
255
|
+
npm install
|
|
181
256
|
```
|
|
182
257
|
|
|
183
258
|
- Compile the Typescript code
|
|
184
259
|
|
|
185
260
|
```sh-session
|
|
186
|
-
|
|
187
|
-
|
|
261
|
+
npm run build
|
|
262
|
+
npm run clean # to remove build artifacts
|
|
188
263
|
```
|
|
189
264
|
|
|
190
265
|
- Format the codebase to comply with the linter rules
|
|
191
266
|
|
|
192
267
|
```sh-session
|
|
193
|
-
|
|
268
|
+
npm run fmt
|
|
194
269
|
```
|
|
195
270
|
|
|
196
271
|
- Run the test suites
|
|
197
272
|
|
|
198
273
|
```sh-session
|
|
199
|
-
|
|
200
|
-
|
|
274
|
+
npm run test
|
|
275
|
+
npm run test-coverage # Run tests with coverage
|
|
201
276
|
```
|
|
202
277
|
|
|
278
|
+
## Compatible specification types
|
|
279
|
+
|
|
280
|
+
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 or JSON file formats are accepted file inputs to the CLI.
|
|
281
|
+
|
|
203
282
|
## Contributing
|
|
204
283
|
|
|
205
|
-
Bug reports and pull requests are welcome on GitHub at https://github.com/bump-sh/cli
|
|
284
|
+
Bug reports and pull requests are welcome on GitHub at <https://github.com/bump-sh/cli>. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
|
|
206
285
|
|
|
207
|
-
|
|
286
|
+
## License
|
|
208
287
|
|
|
209
|
-
The
|
|
288
|
+
The Bump CLI project is released under the [MIT License](http://opensource.org/licenses/MIT).
|
|
210
289
|
|
|
211
|
-
|
|
290
|
+
## Code of Conduct
|
|
212
291
|
|
|
213
292
|
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).
|
|
214
293
|
|
package/lib/args.d.ts
CHANGED
package/lib/args.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.otherFileArg = exports.fileArg = void 0;
|
|
3
|
+
exports.overlayFileArg = exports.otherFileArg = exports.fileArg = void 0;
|
|
4
4
|
const fileArg = {
|
|
5
5
|
name: 'FILE',
|
|
6
6
|
required: true,
|
|
@@ -12,3 +12,8 @@ const otherFileArg = {
|
|
|
12
12
|
description: 'Path or URL to a second API documentation file to compute its diff',
|
|
13
13
|
};
|
|
14
14
|
exports.otherFileArg = otherFileArg;
|
|
15
|
+
const overlayFileArg = {
|
|
16
|
+
name: 'OVERLAY_FILE',
|
|
17
|
+
description: 'Path or URL to an overlay file',
|
|
18
|
+
};
|
|
19
|
+
exports.overlayFileArg = overlayFileArg;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import Command from '../command';
|
|
2
|
+
export default class Overlay extends Command {
|
|
3
|
+
static description: string;
|
|
4
|
+
static examples: string[];
|
|
5
|
+
static flags: {
|
|
6
|
+
help: import("@oclif/parser/lib/flags").IBooleanFlag<void>;
|
|
7
|
+
};
|
|
8
|
+
static args: {
|
|
9
|
+
name: string;
|
|
10
|
+
description: string;
|
|
11
|
+
}[];
|
|
12
|
+
run(): Promise<void>;
|
|
13
|
+
applyOverlay(file: string, overlayFile: string): Promise<string>;
|
|
14
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
const tslib_1 = require("tslib");
|
|
4
|
+
const errors_1 = require("@oclif/errors");
|
|
5
|
+
const yaml_1 = require("@stoplight/yaml");
|
|
6
|
+
const definition_1 = require("../definition");
|
|
7
|
+
const command_1 = (0, tslib_1.__importDefault)(require("../command"));
|
|
8
|
+
const flagsBuilder = (0, tslib_1.__importStar)(require("../flags"));
|
|
9
|
+
const args_1 = require("../args");
|
|
10
|
+
const cli_1 = require("../cli");
|
|
11
|
+
const overlay_1 = require("../core/overlay");
|
|
12
|
+
class Overlay extends command_1.default {
|
|
13
|
+
async run() {
|
|
14
|
+
const { args } = this.parse(Overlay);
|
|
15
|
+
const newDefinition = await this.applyOverlay(args.FILE, args.OVERLAY_FILE);
|
|
16
|
+
cli_1.cli.log(newDefinition);
|
|
17
|
+
return;
|
|
18
|
+
}
|
|
19
|
+
async applyOverlay(file, overlayFile) {
|
|
20
|
+
const api = await definition_1.API.load(file);
|
|
21
|
+
const definition = api.definition;
|
|
22
|
+
this.d(`${file} looks like an ${api.specName} spec version ${api.version}`);
|
|
23
|
+
const overlay = await definition_1.API.load(overlayFile);
|
|
24
|
+
const overlayDefinition = overlay.definition;
|
|
25
|
+
if (!definition_1.API.isOpenAPIOverlay(overlayDefinition)) {
|
|
26
|
+
throw new errors_1.CLIError(`${overlayFile} does not look like an OpenAPI overlay`);
|
|
27
|
+
}
|
|
28
|
+
cli_1.cli.action.start("* Let's apply the overlay to the main definition");
|
|
29
|
+
const newDefinition = (0, overlay_1.applyOverlay)(definition, overlayDefinition);
|
|
30
|
+
cli_1.cli.action.stop();
|
|
31
|
+
if (file.endsWith('.json')) {
|
|
32
|
+
return JSON.stringify(newDefinition);
|
|
33
|
+
}
|
|
34
|
+
else {
|
|
35
|
+
return (0, yaml_1.safeStringify)(newDefinition);
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
exports.default = Overlay;
|
|
40
|
+
Overlay.description = 'Apply an OpenAPI specified overlay to your API definition.';
|
|
41
|
+
Overlay.examples = [
|
|
42
|
+
`$ bump overlay DEFINITION_FILE OVERLAY_FILE
|
|
43
|
+
`,
|
|
44
|
+
];
|
|
45
|
+
Overlay.flags = {
|
|
46
|
+
help: flagsBuilder.help({ char: 'h' }),
|
|
47
|
+
};
|
|
48
|
+
Overlay.args = [args_1.fileArg, args_1.overlayFileArg];
|
|
@@ -15,5 +15,5 @@ export default class Preview extends Command {
|
|
|
15
15
|
}[];
|
|
16
16
|
run(): Promise<void>;
|
|
17
17
|
preview(file: string, open?: boolean, currentPreview?: PreviewResponse | undefined): Promise<PreviewResponse>;
|
|
18
|
-
waitForChanges(file: string,
|
|
18
|
+
waitForChanges(file: string, preview: PreviewResponse): Promise<void>;
|
|
19
19
|
}
|
package/lib/commands/preview.js
CHANGED
|
@@ -11,9 +11,9 @@ const async_mutex_1 = require("async-mutex");
|
|
|
11
11
|
class Preview extends command_1.default {
|
|
12
12
|
async run() {
|
|
13
13
|
const { args, flags } = this.parse(Preview);
|
|
14
|
-
await this.preview(args.FILE, flags.open);
|
|
14
|
+
const currentPreview = await this.preview(args.FILE, flags.open);
|
|
15
15
|
if (flags.live) {
|
|
16
|
-
await this.waitForChanges(args.FILE,
|
|
16
|
+
await this.waitForChanges(args.FILE, currentPreview);
|
|
17
17
|
}
|
|
18
18
|
return;
|
|
19
19
|
}
|
|
@@ -40,17 +40,16 @@ class Preview extends command_1.default {
|
|
|
40
40
|
}
|
|
41
41
|
return response.data;
|
|
42
42
|
}
|
|
43
|
-
async waitForChanges(file,
|
|
43
|
+
async waitForChanges(file, preview) {
|
|
44
44
|
const mutex = new async_mutex_1.Mutex();
|
|
45
|
-
let currentPreview =
|
|
45
|
+
let currentPreview = preview;
|
|
46
46
|
cli_1.cli.action.start(`Waiting for changes on file ${file}...`);
|
|
47
47
|
(0, fs_1.watch)(file, async () => {
|
|
48
48
|
if (!mutex.isLocked()) {
|
|
49
49
|
const release = await mutex.acquire();
|
|
50
|
-
|
|
51
|
-
this.preview(file, firstOpen, currentPreview)
|
|
50
|
+
this.preview(file, false, currentPreview)
|
|
52
51
|
.then((preview) => {
|
|
53
|
-
currentPreview =
|
|
52
|
+
currentPreview = preview;
|
|
54
53
|
cli_1.cli.action.start(`Waiting for changes on file ${file}`);
|
|
55
54
|
})
|
|
56
55
|
.catch((err) => {
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.applyOverlay = void 0;
|
|
4
|
+
const tslib_1 = require("tslib");
|
|
5
|
+
// WIP @github.com/lornajane/openapi-overlays-js
|
|
6
|
+
//
|
|
7
|
+
// I couldn't get the upstream lib to be imported properly due to some
|
|
8
|
+
// issues with ESM module imports so this is file was copied from
|
|
9
|
+
// github.com/lornajane/openapi-overlays-js and has been adapted to
|
|
10
|
+
// make our Typescript build happy.
|
|
11
|
+
//
|
|
12
|
+
// If you make any changes here, please also make them upstream.
|
|
13
|
+
const jsonpath_1 = (0, tslib_1.__importDefault)(require("jsonpath"));
|
|
14
|
+
const mergician_1 = (0, tslib_1.__importDefault)(require("mergician"));
|
|
15
|
+
function applyOverlay(spec, overlay) {
|
|
16
|
+
// Use jsonpath.apply to do the changes
|
|
17
|
+
if (overlay.actions && overlay.actions.length >= 1)
|
|
18
|
+
overlay.actions.forEach((a) => {
|
|
19
|
+
const action = a;
|
|
20
|
+
if (!action.target) {
|
|
21
|
+
process.stderr.write('Action with a missing target\n');
|
|
22
|
+
return;
|
|
23
|
+
}
|
|
24
|
+
const target = action.target;
|
|
25
|
+
// Is it a remove?
|
|
26
|
+
if (action.hasOwnProperty('remove')) {
|
|
27
|
+
while (true) {
|
|
28
|
+
const path = jsonpath_1.default.paths(spec, target, 1);
|
|
29
|
+
if (path.length == 0) {
|
|
30
|
+
break;
|
|
31
|
+
}
|
|
32
|
+
const parent = jsonpath_1.default.parent(spec, target);
|
|
33
|
+
const thingToRemove = path[0][path[0].length - 1];
|
|
34
|
+
if (Array.isArray(parent)) {
|
|
35
|
+
parent.splice(thingToRemove, 1);
|
|
36
|
+
}
|
|
37
|
+
else {
|
|
38
|
+
delete parent[thingToRemove];
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
else {
|
|
43
|
+
try {
|
|
44
|
+
// It must be an update
|
|
45
|
+
jsonpath_1.default.apply(spec, target, (chunk) => {
|
|
46
|
+
// Deep merge using a module (built-in spread operator is only shallow)
|
|
47
|
+
const merger = (0, mergician_1.default)({ appendArrays: true });
|
|
48
|
+
return merger(chunk, action.update);
|
|
49
|
+
});
|
|
50
|
+
}
|
|
51
|
+
catch (ex) {
|
|
52
|
+
process.stderr.write(`Error applying overlay: ${ex.message}\n`);
|
|
53
|
+
//return chunk
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
});
|
|
57
|
+
return spec;
|
|
58
|
+
}
|
|
59
|
+
exports.applyOverlay = applyOverlay;
|
package/lib/definition.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import $RefParser from '@apidevtools/json-schema-ref-parser';
|
|
2
|
-
import { JSONSchema4, JSONSchema4Object, JSONSchema6, JSONSchema6Object, JSONSchema7 } from 'json-schema';
|
|
2
|
+
import { JSONSchema4, JSONSchema4Object, JSONSchema4Array, JSONSchema6, JSONSchema6Object, JSONSchema7 } from 'json-schema';
|
|
3
3
|
declare type SpecSchema = JSONSchema4 | JSONSchema6 | JSONSchema7;
|
|
4
4
|
declare class SupportedFormat {
|
|
5
5
|
static readonly openapi: Record<string, SpecSchema>;
|
|
@@ -22,6 +22,7 @@ declare class API {
|
|
|
22
22
|
resolveContent($refs: $RefParser.$Refs): [string, APIDefinition];
|
|
23
23
|
static isOpenAPI(definition: JSONSchema4Object | JSONSchema6Object): definition is OpenAPI;
|
|
24
24
|
static isAsyncAPI(definition: JSONSchema4Object | JSONSchema6Object): definition is AsyncAPI;
|
|
25
|
+
static isOpenAPIOverlay(definition: JSONSchema4Object | JSONSchema6Object): definition is OpenAPIOverlay;
|
|
25
26
|
extractDefinition(): [string, APIReference[]];
|
|
26
27
|
static load(path: string): Promise<API>;
|
|
27
28
|
}
|
|
@@ -29,14 +30,19 @@ declare type APIReference = {
|
|
|
29
30
|
location: string;
|
|
30
31
|
content: string;
|
|
31
32
|
};
|
|
32
|
-
declare type APIDefinition = OpenAPI | AsyncAPI;
|
|
33
|
+
declare type APIDefinition = OpenAPI | AsyncAPI | OpenAPIOverlay;
|
|
33
34
|
declare type OpenAPI = JSONSchema4Object & {
|
|
34
35
|
readonly openapi?: string;
|
|
35
36
|
readonly swagger?: string;
|
|
36
37
|
readonly info: string;
|
|
37
38
|
};
|
|
39
|
+
declare type OpenAPIOverlay = JSONSchema4Object & {
|
|
40
|
+
readonly overlay: string;
|
|
41
|
+
readonly info: string;
|
|
42
|
+
readonly actions: JSONSchema4Array;
|
|
43
|
+
};
|
|
38
44
|
declare type AsyncAPI = JSONSchema4Object & {
|
|
39
45
|
readonly asyncapi: string;
|
|
40
46
|
readonly info: string;
|
|
41
47
|
};
|
|
42
|
-
export { API, SupportedFormat };
|
|
48
|
+
export { API, APIDefinition, OpenAPIOverlay, SupportedFormat };
|
package/lib/definition.js
CHANGED
|
@@ -53,6 +53,9 @@ class API {
|
|
|
53
53
|
if (API.isAsyncAPI(definition)) {
|
|
54
54
|
return SupportedFormat.asyncapi[this.versionWithoutPatch()];
|
|
55
55
|
}
|
|
56
|
+
else if (API.isOpenAPIOverlay(definition)) {
|
|
57
|
+
return { overlay: { type: 'string' } };
|
|
58
|
+
}
|
|
56
59
|
else {
|
|
57
60
|
return SupportedFormat.openapi[this.versionWithoutPatch()];
|
|
58
61
|
}
|
|
@@ -125,7 +128,9 @@ class API {
|
|
|
125
128
|
if (!parsed || !(parsed instanceof Object) || !('info' in parsed)) {
|
|
126
129
|
throw new UnsupportedFormat("Definition needs to be an object with at least an 'info' key");
|
|
127
130
|
}
|
|
128
|
-
if (!API.isOpenAPI(parsed) &&
|
|
131
|
+
if (!API.isOpenAPI(parsed) &&
|
|
132
|
+
!API.isAsyncAPI(parsed) &&
|
|
133
|
+
!API.isOpenAPIOverlay(parsed)) {
|
|
129
134
|
throw new UnsupportedFormat();
|
|
130
135
|
}
|
|
131
136
|
return [raw, parsed];
|
|
@@ -136,6 +141,9 @@ class API {
|
|
|
136
141
|
static isAsyncAPI(definition) {
|
|
137
142
|
return 'asyncapi' in definition;
|
|
138
143
|
}
|
|
144
|
+
static isOpenAPIOverlay(definition) {
|
|
145
|
+
return 'overlay' in definition;
|
|
146
|
+
}
|
|
139
147
|
extractDefinition() {
|
|
140
148
|
const references = [];
|
|
141
149
|
for (let i = 0; i < this.references.length; i++) {
|
package/lib/index.d.ts
CHANGED
|
@@ -2,5 +2,6 @@ import { run } from '@oclif/command';
|
|
|
2
2
|
import { Diff } from './core/diff';
|
|
3
3
|
import Deploy from './commands/deploy';
|
|
4
4
|
import Preview from './commands/preview';
|
|
5
|
+
import Overlay from './commands/overlay';
|
|
5
6
|
export { VersionResponse, PreviewResponse, DiffResponse, WithDiff } from './api/models';
|
|
6
|
-
export { run, Deploy, Diff, Preview };
|
|
7
|
+
export { run, Deploy, Diff, Preview, Overlay };
|
package/lib/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.Preview = exports.Diff = exports.Deploy = exports.run = void 0;
|
|
3
|
+
exports.Overlay = exports.Preview = exports.Diff = exports.Deploy = exports.run = void 0;
|
|
4
4
|
const tslib_1 = require("tslib");
|
|
5
5
|
const command_1 = require("@oclif/command");
|
|
6
6
|
Object.defineProperty(exports, "run", { enumerable: true, get: function () { return command_1.run; } });
|
|
@@ -10,3 +10,5 @@ const deploy_1 = (0, tslib_1.__importDefault)(require("./commands/deploy"));
|
|
|
10
10
|
exports.Deploy = deploy_1.default;
|
|
11
11
|
const preview_1 = (0, tslib_1.__importDefault)(require("./commands/preview"));
|
|
12
12
|
exports.Preview = preview_1.default;
|
|
13
|
+
const overlay_1 = (0, tslib_1.__importDefault)(require("./commands/overlay"));
|
|
14
|
+
exports.Overlay = overlay_1.default;
|
package/oclif.manifest.json
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":"2.7.
|
|
1
|
+
{"version":"2.7.3-beta","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}},"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":["$ bump overlay DEFINITION_FILE OVERLAY_FILE\n"],"flags":{"help":{"name":"help","type":"boolean","char":"h","description":"show CLI help","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},{"name":"OVERLAY_FILE","description":"Path or URL to an overlay file"}]},"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.7.
|
|
4
|
+
"version": "2.7.3-beta",
|
|
5
5
|
"author": "Paul Bonaud <paulr@bump.sh>",
|
|
6
6
|
"bin": {
|
|
7
7
|
"bump": "./bin/run"
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
"@oclif/dev-cli": "^1.26.0",
|
|
12
12
|
"@oclif/test": "^2.0.3",
|
|
13
13
|
"@types/debug": "^4.1.5",
|
|
14
|
+
"@types/jsonpath": "^0.2.4",
|
|
14
15
|
"@types/mocha": "^10.0.0",
|
|
15
16
|
"@types/node": "^20.7.0",
|
|
16
17
|
"@typescript-eslint/eslint-plugin": "^5.21.0",
|
|
@@ -89,9 +90,12 @@
|
|
|
89
90
|
"@oclif/core": "1.20.4",
|
|
90
91
|
"@oclif/plugin-help": "^5.1.10",
|
|
91
92
|
"@oclif/plugin-warn-if-update-available": "^2.0.36",
|
|
93
|
+
"@stoplight/yaml": "^4.2.3",
|
|
92
94
|
"async-mutex": "^0.4.0",
|
|
93
95
|
"axios": "^0.27.2",
|
|
94
96
|
"debug": "^4.3.1",
|
|
97
|
+
"jsonpath": "^1.1.1",
|
|
98
|
+
"mergician": "^1.0.3",
|
|
95
99
|
"oas-schemas": "git+https://git@github.com/OAI/OpenAPI-Specification.git#0f9d3ec7c033fef184ec54e1ffc201b2d61ce023",
|
|
96
100
|
"tslib": "^2.3.0"
|
|
97
101
|
}
|