From d846e62799d50bf7f1dc046f53aaee469636016d Mon Sep 17 00:00:00 2001 From: "Paul B." Date: Tue, 28 Nov 2023 11:29:18 +0100 Subject: [PATCH 1/4] readme: rewrite the readme for a better help documentation This new readme is also intented to land on docs.bump.sh/help --- README.md | 215 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 148 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 1fe7f113..12cb511e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Bump cli +# Bump CLI

@@ -9,7 +9,13 @@ Sign up

-The Bump CLI is used to interact with your API documentation hosted on Bump by using the API of [developers.bump.sh](https://developers.bump.sh). It is built with [`oclif`](https://oclif.io) in Typescript. +The Bump CLI is used to interact with your API documentation or hubs hosted on Bump.sh. With any API contract of you choice (from Swagger, OpenAPI v3 or AsyncAPI v2), it can help you to: + +- 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 contracts + +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) [![Tests](https://github.com/bump-sh/cli/actions/workflows/checks.yml/badge.svg)](https://github.com/bump-sh/cli/actions/workflows/checks.yml) @@ -26,28 +32,64 @@ The Bump CLI is used to interact with your API documentation hosted on Bump by u ## Installation -Bump is installed via npm. Run this command to install it for local use: +Bump CLI is a node package, currently distributed via NPM which means you need to have Node v14+ interpreter installed on your computer or CI servers. + +_If you are looking to use Bump in a continuous integration environment you might be interested by [our Github Action](https://github.com/marketplace/actions/api-documentation-on-bump)._ + +> You can download a standalone package directly from the latest +> Github release assets if you don’t use Node. We plan to distribute +> universal binaries to common package managers soon. Please check our +> installation methods for updates. +{: .info} + +### Global installation + +To install it globally, run the following command with NPM ```sh-session npm install -g bump-cli ``` -_If you are looking to use Bump in a continuous integration environment you might be interested by [our Github Action](https://github.com/marketplace/actions/api-documentation-on-bump)._ +Or, with Yarn via + +```sh-session +yarn global add bump-cli +``` + +### Add Bump.sh to your node project + +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 +npm install --save-dev bump-cli +``` + +Or with Yarn via + +```sh-session +yarn add --dev bump-cli +``` + +You can then use any Bump commands with `npx` (same as `npm exec`) + +```sh-session +npx bump --help +``` ### How should I do if I'm not using npm ? -Unfortunately, at the moment we only publish a npm package. However we plan to distribute universal binaries in the most common package managers soon. +Unfortunately, at the moment we only support the Node environment. However we plan to distribute universal binaries in the most common package managers very soon. In the meantime, you can download a standalone package directly from the [latest Github release](https://github.com/bump-sh/cli/releases) assets or you can push your documentation using [our API](https://developers.bump.sh/) (advanced usage only). ## Usage -```sh-session -$ npm install -g bump-cli +To list all the available commands, just type `bump` in your command line environment. +```sh-session $ bump --help The Bump CLI is used to interact with your API documentation hosted on Bump by using the API of developers.bump.sh VERSION - bump-cli/2.5.0 linux-x64 node-v16.14.0 + bump-cli/2.7.2 linux-x64 node-v16.17.0 USAGE $ bump [COMMAND] @@ -59,64 +101,78 @@ COMMANDS preview Create a documentation preview from the given file or URL. ``` -Please check the [Bump CLI help page](https://help.bump.sh/bump-cli) for more CLI usage details. + You can also get some help anytime by adding `--help` to any command. Example: `bump deploy --help`. + +## Prepare your Bump.sh account + +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. + +Head to your Documentation Settings in the “CI deployment” section, or your Account or Organization Settings in the “API keys” section to fetch a personnal token for later usage. ## Commands -* [`bump preview [FILE]`](#bump-preview-file) * [`bump deploy [FILE]`](#bump-deploy-file) * [`bump diff [FILE]`](#bump-diff-file) +* [`bump preview [FILE]`](#bump-preview-file) -### `bump preview [FILE]` - -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: +### `bump deploy [FILE]` +When you update your API, you want its documentation to be live for your API users. This is what the deploy command is for. Publish a new API document with this command, and Bump.sh will analyse your API structure and generate a changelog item if the API structure has changed. It will also update your latest published document with the deployed file. ```sh-session -$ bump preview https://bit.ly/asyncapi -* Let's render a preview on Bump... done -* Your preview is visible at: https://bump.sh/preview/c192dad0-79d7-44b3-b5e1-244b69f618e4 (Expires at 2021-06-28T18:06:56+02:00) +bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN ``` -_Note: you can use the `--open` flag to open the preview URL in your browser directly._ +> You can find your own `my-documentation` slug and `$DOC_TOKEN` api key from your [documentation settings](https://bump.sh/docs). +{: .info} -_Note2: you can use the `--live` flag to watch changes of the input `FILE`. This is very helpful when writing your api definition as you will see a live preview being refreshed at each file save._ +You can also deploy a given file to a different branch of your documentation with the `--branch ` parameter. Please note the branch will be created if it doesn’t exist. More details about the branching feature is 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: -Please check `bump preview --help` for more usage details +```sh-session +bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN --branch staging +``` -### `bump deploy [FILE]` +#### Deploy a folder all at once -Deploy the definition file as the current version of the documentation with the following command: +If you already have a hub in your [Bump.sh](https://bump.sh) account, you can automatically create documentation inside it and deploy to it by publishing a whole directory containing multiple API documents in a single command ```sh-session -$ bump deploy path/to/your/file.yml --doc DOC_ID_OR_SLUG --token DOC_TOKEN +bump deploy dir/path/to/apis/ --auto-create --hub my-hub --token $HUB_TOKEN ``` -Deploy the definition file to the `staging` branch of the documentation: +> You can find your own `my-hub` slug and `$HUB_TOKEN` api key from your [hub settings](https://bump.sh/hubs). +{: .info} -```sh-session -$ bump deploy path/to/your/file.yml --doc DOC_ID_OR_SLUG --token DOC_TOKEN --branch staging -``` +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`. Take into account your own file naming convention by using the `--filename-pattern ` option. -If you already have a hub in your [Bump.sh](https://bump.sh) account, you can automatically create a documentation inside it and deploy to it with: +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. + +Here’s a practical example. Suppose you have the following files in your `path/to/apis/` directory: -```sh-session -$ bump deploy path/to/your/file.yml --auto-create --doc DOC_SLUG --hub HUB_ID_OR_SLUG --token HUB_TOKEN +``` +path/to/apis +└─ private-api-users-service.json +└─ partner-api-payments-service.yml +└─ public-api-contracts-service.yml +└─ data.json +└─ README.md ``` -Within a Hub, you can also deploy a whole directory containing multiple API definitions in a single command: +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: -```sh-session -$ bump deploy path/to/your/apis/ --auto-create --hub HUB_ID_OR_SLUG --token HUB_TOKEN ``` +bump deploy path/to/apis/ --hub my-hub --filename-pattern '*-api-{slug}-service' +``` + +#### Validate an API document -Simulate a deployment of your definition file to make sure it is valid with the `--dry-run` flag, it is particularly useful in a Continuous Integration environment running a test deployment outside your main branch: +Simulate a deployment of your API document to make sure it is valid by adding the `--dry-run` flag to the `deploy` command, it is particularly useful in a Continuous Integration environment running a test deployment outside your main branch: ```sh-session -$ bump deploy path/to/your/file.yml --dry-run --doc DOC_ID_OR_SLUG --token DOC_TOKEN +bump deploy path/to/api-document.yml --dry-run --doc my-documentation --token $DOC_TOKEN ``` -Please check `bump deploy --help` for more usage details +Please check `bump deploy --help` for more usage details. ### `bump diff [FILE]` @@ -124,7 +180,7 @@ _If you want to receive automatic `bump diff` results on your Github Pull Reques #### Public API diffs -From any two definition files 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 $ bump diff path/to/your/file.yml path/to/your/second_file.yml @@ -133,42 +189,63 @@ 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 you have a fair use of the service. +{: .info} -Or from two URLs: +_Note: You can also test this feature in our dedicated web application at ._ + +#### 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: ```sh-session -$ bump diff https://demo.bump.sh/doc/trips-books/changes/bfec0a43-b870-44da-9e07-60c8955e15d5.json https://demo.bump.sh/doc/trips-books.json -* Comparing the two given definition files... done -Modified: POST /books - Response modified: 200 - [Breaking] Body attribute removed: cent +bump diff path/to/your/file.yml --doc my-documentation --token $DOC_TOKEN ``` -_Note: You can also test this feature in our dedicated web application at ._ +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 +bump diff path/to/your/file.yml path/to/your/next-file.yml --doc my-documentation --token $DOC_TOKEN +``` -#### Authenticated diffs attached to your Bump documentation +Please check `bump diff --help` for full usage details. -From a Bump documentation, the `diff` command will retrieve a comparison changelog between your existing documentation and the given file or URL: +### `bump preview [FILE]` -```sh-session -$ bump diff path/to/your/file.yml --doc DOC_ID_OR_SLUG --token DOC_TOKEN -* Comparing the given definition file with the currently deployed one... done -Updated: POST /validations - Body attribute modified: documentation +When writing a documentation, you might want to preview how it renders on Bump.sh. This is exactly the goal of the `preview` command: it will create a temporary documentation with a unique URL, which will be available for a short period of time. + +Usage from a local OpenAPI or AsyncAPI file + +```shell +bump preview path/to/file.json ``` -If you want to compare two unpublished versions of your definition file, the `diff` command can retrieve a comparison changelog between two given file or URL, “as simple as `git diff`”: +You can also preview a file available from a URL -```sh-session -$ bump diff path/to/your/file.yml path/to/your/next-file.yml --doc --token -* Comparing the two given definition files... done +```shell +bump preview https://developers.bump.sh/source.yaml +``` + +#### Live preview -Updated: POST /versions - Body attribute added: previous_version_id +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. + +- Launch the live preview command in your terminal + +```shell +bump preview --live --open openapi-definition.json ``` -Please check `bump diff --help` for full usage details. +- Edit your `openapi-definition.json` file in your favorite text editor +- Watch the live preview being updated each time your save your file! + +> 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 ## Development @@ -177,38 +254,42 @@ Make sure to have Node.js (At least v14) installed on your machine. - Install node dependencies with ```sh-session - $ npm install + npm install ``` - Compile the Typescript code ```sh-session - $ npm run build - $ npm run clean # to remove build artifacts + npm run build + npm run clean # to remove build artifacts ``` - Format the codebase to comply with the linter rules ```sh-session - $ npm run fmt + npm run fmt ``` - Run the test suites ```sh-session - $ npm run test - $ npm run test-coverage # Run tests with coverage + npm run test + npm run test-coverage # Run tests with coverage ``` +## Compatible specification types + +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. + ## 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. +Bug reports and pull requests are welcome on GitHub at . 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. -### License +## License -The node package is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT). +The Bump CLI project is released under the [MIT License](http://opensource.org/licenses/MIT). -### Code of Conduct +## 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). From 6f48aa1efef7352f5bf9b4c7a92287ed40585268 Mon Sep 17 00:00:00 2001 From: Paul B Date: Wed, 29 Nov 2023 19:48:33 +0100 Subject: [PATCH 2/4] Apply suggestions from Jay review Co-authored-by: jayk-u <34686012+jayk-u@users.noreply.github.com> --- README.md | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 12cb511e..008e3822 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,11 @@ Sign up

-The Bump CLI is used to interact with your API documentation or hubs hosted on Bump.sh. With any API contract of you choice (from Swagger, OpenAPI v3 or AsyncAPI v2), it can help you to: +The Bump CLI is used to interact with your API documentation or hubs hosted on Bump.sh. With any API definition of you choice (from Swagger, OpenAPI or AsyncAPI), it can help you to: - 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 contracts +- Compare two API documents to generate a human-readable diff from your API definitions 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. @@ -37,9 +37,7 @@ Bump CLI is a node package, currently distributed via NPM which means you need t _If you are looking to use Bump in a continuous integration environment you might be interested by [our Github Action](https://github.com/marketplace/actions/api-documentation-on-bump)._ > You can download a standalone package directly from the latest -> Github release assets if you don’t use Node. We plan to distribute -> universal binaries to common package managers soon. Please check our -> installation methods for updates. +> Github release assets if you don’t use Node. {: .info} ### Global installation @@ -78,7 +76,7 @@ npx bump --help ### How should I do if I'm not using npm ? -Unfortunately, at the moment we only support the Node environment. However we plan to distribute universal binaries in the most common package managers very soon. In the meantime, you can download a standalone package directly from the [latest Github release](https://github.com/bump-sh/cli/releases) assets or you can push your documentation using [our API](https://developers.bump.sh/) (advanced usage only). +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). ## Usage @@ -86,7 +84,7 @@ To list all the available commands, just type `bump` in your command line enviro ```sh-session $ bump --help -The Bump CLI is used to interact with your API documentation hosted on Bump by using the API of developers.bump.sh +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.7.2 linux-x64 node-v16.17.0 @@ -107,7 +105,7 @@ COMMANDS 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. -Head to your Documentation Settings in the “CI deployment” section, or your Account or Organization Settings in the “API keys” section to fetch a personnal token for later usage. +Head 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. ## Commands @@ -117,7 +115,7 @@ Head to your Documentation Settings in the “CI deployment” section, or your ### `bump deploy [FILE]` -When you update your API, you want its documentation to be live for your API users. This is what the deploy command is for. Publish a new API document with this command, and Bump.sh will analyse your API structure and generate a changelog item if the API structure has changed. It will also update your latest published document with the deployed file. +When you update your API, you want its documentation to be live for your API users. This is what the deploy command is for. ```sh-session bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN @@ -126,7 +124,7 @@ bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN > You can find your own `my-documentation` slug and `$DOC_TOKEN` api key from your [documentation settings](https://bump.sh/docs). {: .info} -You can also deploy a given file to a different branch of your documentation with the `--branch ` parameter. Please note the branch will be created if it doesn’t exist. More details about the branching feature is 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: +You can also deploy a given API document to a different branch of your documentation with the `--branch ` parameter. Please note the branch will be created if it doesn’t exist. More details about the branching feature is 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 bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN --branch staging @@ -147,7 +145,7 @@ Please note, by default, only files named `{slug}-api.[format]` are published. W 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. -Here’s a practical example. Suppose you have the following files in your `path/to/apis/` directory: +Here’s a practical example. Let's assume that you have the following files in your `path/to/apis/` directory: ``` path/to/apis @@ -158,7 +156,7 @@ path/to/apis └─ README.md ``` -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: +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: ``` bump deploy path/to/apis/ --hub my-hub --filename-pattern '*-api-{slug}-service' @@ -189,7 +187,7 @@ 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 you have a fair use of the service. +> 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 ._ @@ -213,7 +211,7 @@ Please check `bump diff --help` for full usage details. ### `bump preview [FILE]` -When writing a documentation, you might want to preview how it renders on Bump.sh. This is exactly the goal of the `preview` command: it will create a temporary documentation with a unique URL, which will be available for a short period of time. +When writing a documentation, you might want to preview how it renders on Bump.sh. This is precisely the goal of the `preview` command: it will create a temporary documentation with a unique URL, which will be available for a short period. Usage from a local OpenAPI or AsyncAPI file @@ -238,7 +236,7 @@ bump preview --live --open openapi-definition.json ``` - Edit your `openapi-definition.json` file in your favorite text editor -- Watch the live preview being updated each time your save your file! +- Watch the live preview being updated each time you save your file. > You can create as many previews as you like without being authenticated. This is a **free and unlimited service**. {: .info} From f2f3a5143103f44dbb936a40dd9c749b4bf49681 Mon Sep 17 00:00:00 2001 From: Paul B Date: Thu, 30 Nov 2023 09:25:59 +0100 Subject: [PATCH 3/4] Apply suggestions from Jay review Co-authored-by: jayk-u <34686012+jayk-u@users.noreply.github.com> --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 008e3822..20f7d25f 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Sign up

-The Bump CLI is used to interact with your API documentation or hubs hosted on Bump.sh. With any API definition of you choice (from Swagger, OpenAPI or AsyncAPI), it can help you to: +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: - Validate an API document before publishing to your documentation - Publish an API document to your Bump.sh documentation or hubs @@ -32,9 +32,9 @@ Under the hood, it uses the API of [developers.bump.sh](https://developers.bump. ## Installation -Bump CLI is a node package, currently distributed via NPM which means you need to have Node v14+ interpreter installed on your computer or CI servers. +Bump.sh CLI is a node package currently distributed via NPM which means you need to have Node v14+ interpreter installed on your computer or CI servers. -_If you are looking to use Bump 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/api-documentation-on-bump)._ > You can download a standalone package directly from the latest > Github release assets if you don’t use Node. @@ -68,7 +68,7 @@ Or with Yarn via yarn add --dev bump-cli ``` -You can then use any Bump commands with `npx` (same as `npm exec`) +You can then use any Bump.sh commands with `npx` (same as `npm exec`) ```sh-session npx bump --help From 64500c256afc6e6fb1b8095b2fd741290a9e18e0 Mon Sep 17 00:00:00 2001 From: "Paul B." Date: Wed, 13 Dec 2023 17:15:26 +0100 Subject: [PATCH 4/4] Apply suggestions from Chris (from the Docs repo PR) https://github.com/bump-sh/docs/pull/147/commits/8c3cb5f9c42dd0ef948015e4cc6c7150bdb39fee --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 20f7d25f..c6a74365 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Under the hood, it uses the API of [developers.bump.sh](https://developers.bump. ## Installation -Bump.sh CLI is a node package currently distributed via NPM which means you need to have Node v14+ interpreter installed on your computer or CI servers. +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. _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)._ @@ -105,7 +105,7 @@ COMMANDS 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. -Head 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. +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. ## Commands @@ -115,7 +115,7 @@ Head to your Documentation settings in the “CI deployment” section, or your ### `bump deploy [FILE]` -When you update your API, you want its documentation to be live for your API users. This is what the deploy command is for. +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. ```sh-session bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN @@ -124,7 +124,7 @@ bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN > You can find your own `my-documentation` slug and `$DOC_TOKEN` api key from your [documentation settings](https://bump.sh/docs). {: .info} -You can also deploy a given API document to a different branch of your documentation with the `--branch ` parameter. Please note the branch will be created if it doesn’t exist. More details about the branching feature is 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: +You can also deploy a given API document to a different branch of your documentation with the `--branch ` 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 bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN --branch staging @@ -132,7 +132,7 @@ bump deploy path/to/api-document.yml --doc my-documentation --token $DOC_TOKEN - #### 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 inside it and deploy to it by publishing a whole directory containing multiple API documents in a single command +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 bump deploy dir/path/to/apis/ --auto-create --hub my-hub --token $HUB_TOKEN @@ -141,7 +141,7 @@ bump deploy dir/path/to/apis/ --auto-create --hub my-hub --token $HUB_TOKEN > You can find your own `my-hub` slug and `$HUB_TOKEN` api key from your [hub settings](https://bump.sh/hubs). {: .info} -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`. Take into account your own file naming convention by using the `--filename-pattern ` option. +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 ` option. 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. @@ -164,7 +164,7 @@ bump deploy path/to/apis/ --hub my-hub --filename-pattern '*-api-{slug}-service' #### Validate an API document -Simulate a deployment of your API document to make sure it is valid by adding the `--dry-run` flag to the `deploy` command, it is particularly useful in a Continuous Integration environment running a test deployment outside your main branch: +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 bump deploy path/to/api-document.yml --dry-run --doc my-documentation --token $DOC_TOKEN @@ -211,7 +211,7 @@ Please check `bump diff --help` for full usage details. ### `bump preview [FILE]` -When writing a documentation, you might want to preview how it renders on Bump.sh. This is precisely the goal of the `preview` command: it will create a temporary documentation with a unique URL, which will be available for a short period. +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