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

readme tidy #647

Merged
merged 4 commits into from
Jan 28, 2025
Merged

readme tidy #647

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7d426b2
docs: tidied up the README a little
philsturgeon Jan 28, 2025
e592902
toc links to new headers
philsturgeon Jan 28, 2025
2748587
returned a new mention of CI=1
philsturgeon Jan 28, 2025
6d9f607
merge compatibility into intro
philsturgeon Jan 28, 2025
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
189 changes: 101 additions & 88 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,17 @@
</p>

<p align="center">
<a href="https://help.bump.sh/">Help</a> |
<a href="https://docs.bump.sh/help">Help</a> |
<a href="https://bump.sh/users/sign_up">Sign up</a>
</p>

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:
The Bump.sh CLI is used to interact with API documentation and hubs hosted on Bump.sh from your choice of popular API description formats: OpenAPI, Swagger, or AsyncAPI.

- Validate an API document before publishing it to your documentation
- Publish an API document to your Bump.sh documentation or hubs
- Compare two API documents to generate a human-readable diff from your API definitions
Using [OpenAPI](https://github.com/OAI/OpenAPI-Specification) (v3.x and v2.0) or [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest) (2.x), you can do any of the following:

- Validate an API document before publishing to your documentation.
- Publish an API document to your Bump.sh documentation or hubs.
- Compare two API documents to generate a human-readable diff from your API definition.
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.

[![Version](https://img.shields.io/npm/v/bump-cli.svg)](https://npmjs.org/package/bump-cli)
Expand All @@ -34,43 +35,43 @@ Under the hood, it uses the API of [developers.bump.sh](https://developers.bump.

The Bump.sh CLI is a node package currently distributed via NPM. This means you must have the Node v20+ interpreter installed on your computer or CI servers.

_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)._
_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/bump-sh-api-documentation-changelog)._

> You can download a standalone package directly from the latest
> GitHub release assets if you don’t use Node.
> Github release assets if you don’t use Node.
{: .info}

### Global installation

To install it globally, run the following command with NPM
To install it globally, run the following command with NPM:

```sh-session
```shell
npm install -g bump-cli
```

Or, with Yarn via
Or, with Yarn via:

```sh-session
```shell
yarn global add bump-cli
```

### Add Bump.sh to your Node project

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
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:

```sh-session
```shell
npm install --save-dev bump-cli
```

Or with Yarn via
Or with Yarn via:

```sh-session
```shell
yarn add --dev bump-cli
```

You can then use any Bump.sh commands with `npx` (same as `npm exec`)
You can then use any Bump.sh commands with `npx` (same as `npm exec`):

```sh-session
```shell
npx bump --help
```

Expand All @@ -82,12 +83,12 @@ Unfortunately, at the moment we only support the Node environment. However, you

To list all the available commands, just type `bump` in your command line environment.

```sh-session
```shell
$ bump --help
The Bump.sh CLI is used to interact with your API documentation hosted on Bump.sh by using the API of developers.bump.sh

VERSION
bump-cli/2.9.1 linux-x64 node-v20.18.1
bump-cli/2.9.2 linux-x64 node-v20.18.1

USAGE
$ bump [COMMAND]
Expand All @@ -110,16 +111,16 @@ Head over to your Documentation settings in the “CI deployment” section or y

## Commands

* [`bump deploy [FILE]`](#bump-deploy-file)
* [`bump diff [FILE]`](#bump-diff-file)
* [`bump preview [FILE]`](#bump-preview-file)
* [`bump overlay [DEFINITION_FILE] [OVERLAY_FILE]`](#bump-overlay-definition_file-overlay_file)
* [`bump deploy [FILE]`](#the-deploy-command)
* [`bump diff [FILE]`](#the-diff-command)
* [`bump preview [FILE]`](#the-preview-command)
* [`bump overlay [DEFINITION_FILE] [OVERLAY_FILE]`](#the-overlay-command)

### `bump deploy [FILE]`
### The `deploy` command

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.
When an API is updated, the documentation should be updated at the same time. This is what the deploy command is for.

```sh-session
```shell
bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN
```

Expand All @@ -128,15 +129,15 @@ bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN

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:

```sh-session
```shell
bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN --branch staging
```

#### Deploy a folder all at once

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:

```sh-session
```shell
bump deploy dir/path/to/apis/ --auto-create --hub my-hub --token $HUB_TOKEN
```

Expand Down Expand Up @@ -168,69 +169,81 @@ bump deploy path/to/apis/ --hub my-hub --filename-pattern '*-api-{slug}-service'

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:

```sh-session
```shell
bump deploy path/to/api-document.yml --dry-run --doc my-documentation --token $DOC_TOKEN
```

Please check `bump deploy --help` for more usage details.

### `bump diff [FILE]`

_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/bump-sh-api-documentation-changelog) which also has a diff command._
### The `diff` command

Please note that by default the command will always exit with a
successful return code. If you want to use this command in a CI
environment and want the command to fail **in case of a breaking
change**, you will need to add the `--fail-on-breaking` flag to your
diff command. By default if the environment variable `CI=1` is present
(in most continuous integration environment), the flag will be
enabled. In that case you can disable the failures with
`--no-fail-on-breaking` flag.
Using the `diff` command can help to spot differences between the local API
document and the latest deployed version.

#### Public API diffs

From any two API documents or URLs, you can retrieve a comprehensive changelog of what has changed between them.
From any two API documents or URLs, you can retrieve a comprehensive changelog
of what has changed between them.

```sh-session
```shell
$ bump diff path/to/your/file.yml path/to/your/second_file.yml
* Comparing the two given definition files... done
Modified: GET /consommations
Response modified: 200
[Breaking] Body attribute modified: energie
```
> 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.
{: .info}

_**Note:** You can also test this feature in our dedicated web application at <https://api-diff.io/>._
By default the command will always exit with a successful return code. If you
want to use this command in a CI environment and want the command to fail **in
case of a breaking change**, you will need to add the `--fail-on-breaking` flag
to your diff command.

By default if the environment variable `CI=1` is present (in most continuous
integration environment), the flag will be enabled. In that case you can disable
the failures with `--no-fail-on-breaking` flag.

You can also test this feature in our dedicated web application at
<https://api-diff.io/>.

#### GitHub Integration

If you want to receive automatic `bump diff` results on Github Pull Requests you
might be interested by [our Github
Action](https://github.com/marketplace/actions/bump-sh-api-documentation-changelog#deploy-documentation--diff-on-pull-requests)
which has support for the diff command.

#### Authenticated diffs related to your Bump.sh documentation

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:
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:

```sh-session
```shell
bump diff path/to/your/file.yml --doc my-documentation --token $DOC_TOKEN
```

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`”:

```sh-session
```shell
bump diff path/to/your/file.yml path/to/your/next-file.yml --doc my-documentation --token $DOC_TOKEN
```

Please check `bump diff --help` for full usage details.

### `bump preview [FILE]`
### The `preview` command

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).

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).

Usage from a local OpenAPI or AsyncAPI file
Usage from a local OpenAPI or AsyncAPI document:

```shell
bump preview path/to/file.json
```

You can also preview a file available from a URL
You can also preview a document available via a URL:

```shell
bump preview https://developers.bump.sh/source.yaml
Expand All @@ -243,37 +256,48 @@ By using the `--live` flag you can stay focused on API design (OpenAPI or AsyncA
- Launch the live preview command in your terminal

```shell
bump preview --live --open openapi-definition.json
bump preview --live --open api-document.yaml
```

- Edit your `openapi-definition.json` file in your favorite text editor
- Edit your `api-document.yaml` file in your favorite text editor.
- Watch the live preview being updated each time you save your file.
- The additional `--open` flag helps to automatically open the preview URL in your browser.

> You can create as many previews as you like without being authenticated. This is a **free and unlimited service**.
{: .info}

_**Note:** the additional `--open` flag helps to automatically open the preview URL in your browser._

Please check `bump preview --help` for more usage details

### `bump overlay [DEFINITION_FILE] [OVERLAY_FILE]`
### The `overlay` command

> 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.
The [Overlay Specification](https://spec.openapis.org/overlay/v1.0.0.html) from the OpenAPI Initiative makes it possible to modify the content of an API definition 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.

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.
The `bump overlay` command takes an original API document, applies the changes from the overlay document, and outputs a modified version. No changes are made directly to the original document.

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.
```shell
bump overlay api-document.yaml overlay.yaml
```

To redirect the output of the command to a new file you can run:

```shell
bump overlay api-document.yaml overlay.yaml > modified-api-document.yaml
```

To redirect the output of the command to a new file you can run the following:
You can also apply the overlay using the [`deploy` command](#the-deploy-command) with the `--overlay` flag:

```shell
bump overlay api-document.yaml overlay-file.yaml > api-overlayed-document.yaml
bump deploy api-document.yaml --doc my-doc --token my-token --overlay overlay.yaml
```

_Note: you can also apply overlays during the [`bump deploy` command]((#bump-deploy-file)) with the `--overlay` flag (which can be used multiples times):_
If there are multiple overlays which need to be applied, the `--overlay` can be passed multiple times.

```shell
bump deploy api-document.yaml --doc my-doc --token my-token --overlay overlay-file.yaml
bump deploy api-document.yaml \
--doc my-doc \
--token my-token \
--overlay overlay1.yaml \
--overlay overlay2.yaml
```

## Development
Expand All @@ -282,55 +306,44 @@ Make sure to have Node.js (At least v20) installed on your machine.

- Install node dependencies with

```sh-session
```shell
npm install
```

- Compile the Typescript code

```sh-session

```shell
npm run build
npm run clean # to remove build artifacts
npm run clean # Remove build artifacts
```

- Format the codebase to comply with the linter rules

```sh-session
```shell
npm run fmt
```

- Run the test suites

```sh-session
```shell
npm run test
npm run test-coverage # Run tests with coverage
```

## Compatible specification types
## License

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.
The Bump CLI project is released under the [MIT License](http://opensource.org/licenses/MIT).

## Contributing

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.

## Thanks

- [Lorna Mitchel](https://github.com/lornajane/) for [openapi-overlay-js](https://github.com/lornajane/openapi-overlays-js)

## License

The Bump CLI project is released under the [MIT License](http://opensource.org/licenses/MIT).

## Code of Conduct

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).

## Versioning

This npm package starts at v2.0.0 for two main reasons:

- 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
## Thanks

- 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!_
w
- [Lorna Mitchel](https://github.com/lornajane/) for [openapi-overlay-js](https://github.com/lornajane/openapi-overlays-js).
- [Rico](https://github.com/rstacruz) for transferring the ownership of the `bump-cli` package name.
Loading