We have implemented this in our builds to do comparison on our documentation to detect breaking changes. It works very well. However every once and a while when teams have an aggressive amount of building the tool seems to break with a "try again later" error message. I was wondering if this tool has some built in throttling in lines with the comment from your documentation here.

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}

I am looking into using Bump as a documentation system for the new API my company is building, and I'm running into an error whenever I attempt to reference an external Markdown file in a topic.

I have "bump-preview": "bump preview resources/openapi/openapi.yaml" defined in my package.json scripts, so when I run yarn bump-preview I see this output.

$ yarn bump-preview
yarn run v1.22.5
$ bump preview resources/openapi/openapi.yaml
* Let's render a preview on Bump... !
 ›   Error: raw_definition property '/x-topics/0/content' is not of type: string
error Command failed with exit code 122.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
yarn run v1.22.5
$ bump preview resources/openapi/openapi.yaml
* Let's render a preview on Bump... !
 ›   Error: raw_definition property '/x-topics/0/content' is not of type: string
error Command failed with exit code 122.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

The entirety of my openapi.yaml file is

openapi: 3.1.0
info:
  title: Bump CLI
  version: dev
  description: Test bump-cli
x-topics:
  - title: Test Markdown
    content:
      $ref: '../docs/test.md'
paths: {}

as I wanted to keep things minimal for this report, and the markdown file located at ../docs/test.md relative to that file is

# External Markdown

Some external markdown file.

If I change the path to an invalid location, it gives me an appropriate file-not-found error, so it appears to be finding the file correctly. Also, if I put that exact Markdown directly in the yaml file it previews correctly, so there appears to be some issue with the output of the Markdown parser.

Newly generated public diffs with the bump diff command will generate a public diff page which expires in 1 day.

However, so user might want the diff page to expire later, or never expire.

We should thus add a --expire CLI parameter to let the user decide.

For now the preview command can only be used to preview a api definition file in one go, without any of the available settings of a Bump documentation (color, logo, grouping, name, etc...).

It would thus be nice if we could preview a file with --doc doc-slug --token doc-token paramters. Thus, we could deploy it to an existing documentation, without impacting the “offical” deploy history.

Note: would it be better to enhance the preview command or add a parameter to the deploy command (e.g. deploy --preview)

I updated lots of parts of our Help pages to prepare for the new CLI release.

Could someone take a look / review my changes please?

Steps to reproduce

> bump deploy inexistent/dir/ --auto-create --hub "my-hub" --token "my-token"
 ›   Error: Missing required flag:
 ›    -d, --doc DOC  Documentation public id or slug. Can be provided via BUMP_ID environment variable
 ›   See more help with --help

Expected behavior

A better error message, stating that the target directory inexistent/dir/ doesn't exist.

As discussed today with Sébastien, we think it's better to continue to offer the call to the validate API via a flag on the deploy command, such as:

bump deploy --dry-run FILE.json

Current behavior

When using the bump deploy my/directory to deploy multiple API documents to a Bump.sh Hub, the command fails as soon as one of the deployment fails.

Suggested behavior

It would be nice if the “multiple deploy” command doesn't stop on first error. Instead it would be nice if it gathers all potential errors by trying to deploy all the files from the directory, and at the end fail if any of the deployment failed.

Hi,

I've used the https://api-diff.io/ to compare two versions of an api.
In the second version a content type return data was deleted but this non backward compatible change was not detected by https://api-diff.io/ : "No API structure changes detected"

Here the two files I used
Simple-API-V1.yaml.txt
Simple-API-V2.yaml.txt

This breaking change is detected by https://github.com/OpenAPITools/openapi-diff :

`C:\openapi-diff-master\cli>java -jar target\openapi-diff-cli-2.1.0-SNAPSHOT-all.jar Simple-API-V1.yaml Simple-API-V2.yaml

== API CHANGE LOG ==

                            Simple API

-- What's Changed --

• GET /users/{userId}
  Return Type:
  • Changed 200 OK
    Media types:
    • Deleted application/xml

-- Result --

             API changes broke backward compatibility

`

Context

For now if you want to deploy multiple API contracts to a single Hub, you need to call our github-action (or CLI) for each contract file.
This is not very convenient especially when you use a repo with automatic deployment.

The current “solution” is to use a manual script to deploy all files in a single CI run (e.g. in our examples repository) .

Solution

We should allow the bump deploy command to deploy a whole directory to a given hub. This would simplify our users' CI definition and make the relation between a directory and a Bump hub clear.

e.g. Deploy the hubs/api-contracts/ directory to the my-train-company hub would be as simple as:

bump deploy --hub my-train-company hubs/api-contracts/

-> Functional Specifications

Rabbit hole

We will need a way to define the mapping between file names and documentation names. We thus probably need to have a bump config file to be able to configure this.
We rely on filename: following the convention name of the Bump.sh examples repository.

Hi,

Step to reproduce :
A folder with two files :

• topic.md
• spec.json (spec OpenAPI)

in spec.jons :

...
"x-topics": [
    {
      "title": "A topic",
      "content": {
            "$ref": "./topic.md"
    }
  ]
...

With cli :
/> bump preview

Result : topic.md not merged

Context

Imagine you want to import the history of changes of a given API definition file to Bump.

The current “solution” is to use a manual script to deploy each revision one by one. Very rough-and-not-working oneliner bash script: git log --pretty=format:%H my/definition/openapi.yml | xargs -I % git show '%:my/definition/openapi.yml.

Solution

We should allow the bump deploy command to deploy a git history of a given file. This would simplify our users' initial import work.

e.g. Deploy the my/definition/openapi.yml file to the my-doc documentation would be as simple as:

bump deploy --git-history --doc my doc my/definition/openapi.yml

We could also allow --from / --to options such as:

bump deploy --git-history --from c900e6 --to main --doc my doc my/definition/openapi.yml

Is there any way that the file input could be from a pandas dataframe? I have a df wherein I have a column named url in the following format:

Example URL
Is there a way I can pass as input the url I stated above so that it calculated the diff between all the files sorted by their id and dates?

Hello!

I am using bump-cli in my gitlab-ci. It works well most of the time, whether documentation has changed or not.
But sometimes, it throws the error below (as I do a --dry-run before the real deploy and can't reproduce everytime, I don't know if I would get the same error during the real deploy).

$ npm install -g bump-cli
$ bump deploy --dry-run bump/diff.json --token ${BUMP_TOKEN} --doc engagement --branch ${CI_COMMIT_BRANCH}
 ›   Error: Error parsing /builds/rh/engagement/pfe/bump/diff.json: 
 ›   unexpected end of the stream within a flow collection (2:1)
 ›
 ›    1 | { "openapi": "3.0.0", "info": {  ...
 ›    2 | 
 ›   -----^

The way I generate the json file does not change. Do you know what could cause this error?
Thank you !

For now, if you wish to publish a new release of the CLI you need to:

1. git checkout main
2. npm run release for a full release (or npm run release -- --tag beta for a prerelease where --tag is the dist tag of your choice)
3. The script above will prompt for the version upgrade you desire (patch, minor or major)
4. Then it will do all this for you:

• Check your in the right place
• Check the version your trying to publish doesn't exist yet
• Re-install npm dependencies from scratch
• Run tests
• Bump version with npm version ...
• Publish package on npm
• Push a git tag v<version>

1. Wait for the CI to run on the pushed git tag (the CI will create a draft github release with standalone tarballs attached to it)
2. Edit the newly created draft release to write release notes 📝 and publish the github release 🚀

Package distribution

With the above process we will only distribute a NPM package + standalone tarballs on the Github Release. For the future we will need to distribute packages in common package managers (Homebrew, .deb, .rpm & .aur, Docker, Nix, Snap ...?)

Hi,
I'm trying to define JWT and API key security.
Only first security schemes is displayed ith bump preview
My spec looks like :

...
 "components": {
    "securitySchemes": {
      "my_jwt": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "my_api_key": {
        "type": "apiKey",
        "name": "Ocp-Apim-Subscription-Key",
        "in": "header"
      }
    }
}
...
...
"security": [
    {
      "my_jwt": [],
      "my_api_key": []
    }
  ]
...

Actual result :

curl \
 -X GET https://{uri} \
 -H "Authorization: Bearer $ACCESS_TOKEN"

Expected :

curl \
 -X GET https://{uri} \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Ocp-Apim-Subscription-Key: $API_KEY"

The idea behind this is to be able to configure your bump account locally with a bump config command (and most probably a bump login one to initialize the configuration file)

Bump CLI fails to validate that the diff of a file with itself is always empty.

It was the case in the past, and now it fails.
Here is the a gist of the file: https://gist.github.com/noudin-ledger/66d6d2bac60e43fd467f25287d436e89
This fails with:

$ bump diff api-spec.yaml api-spec.yaml
* Comparing the two given definition files... done
Modified: GET /schema/{schema_id}
  Response modified: 200
    Content type modified: application/json
      [Breaking] Attribute modified: all2
        [Breaking] Alternative removed: AllOf1
        [Breaking] Alternative added: AllOf1

The error is triggered by the fact that the SchemaEntry schema component contains two properties that are defined by a allOf. If I remove one of the two, it works.
As I have seen no change in the code that could explain this, I think it might be a dependency issue, but I haven't nailed it down yet.
The error in itself seems to show that bump cli fails to detect that AllOf1 and AllOf1 are the same:

[Breaking] Alternative removed: AllOf1
[Breaking] Alternative added: AllOf1

Extra informations:

$ bump --version
bump-cli/2.7.3 linux-x64 node-v18.16.0

$ node --version
v18.16.0

$ lsb_release -a
No LSB modules are available.
Distributor ID:	Ubuntu
Description:	Ubuntu 22.04.4 LTS
Release:	22.04
Codename:	jammy

I installed bump with yarn global add bump-cli

deepanshachowdhary@Deepanshas-MacBook-Pro cli % bump diff https://github.com/wicrs/docs/blob/8e0e99de1db6fb9b3d04361b80652e4972ed727b/json/swagger-resolved.json https://github.com/wicrs/docs/blob/bcfa0c9125ff5808388bc7c12aba41f76d91c153/json/swagger-resolved.json Error: Cannot find module 'oas-schemas/schemas/v2.0/schema.json' Require stack: - /usr/local/lib/node_modules/bump-cli/lib/definition.js - /usr/local/lib/node_modules/bump-cli/lib/core/diff.js - /usr/local/lib/node_modules/bump-cli/lib/commands/diff.js - /usr/local/lib/node_modules/bump-cli/node_modules/@oclif/config/lib/plugin.js - /usr/local/lib/node_modules/bump-cli/node_modules/@oclif/config/lib/config.js - /usr/local/lib/node_modules/bump-cli/node_modules/@oclif/config/lib/index.js - /usr/local/lib/node_modules/bump-cli/node_modules/@oclif/command/lib/command.js - /usr/local/lib/node_modules/bump-cli/node_modules/@oclif/command/lib/index.js - /usr/local/lib/node_modules/bump-cli/bin/run Code: MODULE_NOT_FOUND

I get the following error when I try to run bump.sh locally on my machine, I installed all the required packages, but I am not able to figure out where the error comes from. Is it a missing package on my side?

With the live preview command bump preview --live if the provided definition uses file system based references, then those external references are not “watched” by the CLI.

E.g. openapi.yaml

paths:
  /v1/version:
    $ref: 'v1/version.yaml'

With a Path Item object of the /v1:version endpoint in the external file v1/version.yaml

Steps to reproduce

• Launch the live preview command bump preview --live --open openapi.yaml
• Change the v1/version.yaml file
• Nothing happens

What should happen

• Launch the live preview command bump preview --live --open openapi.yaml
• Change the v1/version.yaml file
• The preview should be updated with the latest file system changes

Hi,
Can you look at the possibility to put a fallback url in the header of the documentation page ?
Use case :

• I am on my portal, i go to bump documentation
• I need return to my portal

Regards

Needs to be mentioned in README and tested in CI

Following #465,

We noticed that, if Bump.sh API returned a new HTTP error code (for example 402), currently it's necessary
to add specific code to support this 402 status error, available only with a release of the CLI.

It could be nice to add a default treatment of any HTTP error code, to make sure any error from Bump.sh API is 'understood' by CLI, and that provided error message (with JSON) is displayed.

This has been broken since release of 2.7.0. We can't deploy from a URL.

bump deploy https://developers.bump.sh/source.json -d bump
    Error: ENOENT: no such file or directory, stat 'https://developers.bump.sh/source.json'
    Code: ENOENT

We need to fully migrate to the @oclif/core library to remove any usage of the now deprecated @oclif/command lib.

Hi,

I would like use bump-cli to track changes in specification. However I notice that there is a noise changes detected.

$ npm list  | grep 'bump-cli'
└── [email protected]
$ curl "https://api.production.selectstar.com/swagger/?format=openapi" | jq '.' > ./remote-openapi.json
...
$ ./node_modules/.bin/bump diff remote-openapi.json remote-openapi.json
* Comparing the two given definition files... done
[Breaking] Modified: PATCH /tags/{guid}/
  [Breaking] Body modified
    Attributes added: guid, name, description, richtext_description, icon, color, parent, ordinal, updated_on, owner, breadcrumbs, visible
    [Breaking] Attribute removed: items
  [Breaking] Response modified: 200
    Attributes added: guid, name, description, richtext_description, icon, color, parent, ordinal, updated_on, owner, breadcrumbs, visible
    [Breaking] Attribute removed: items

I would expect that the specification compared with itself is not able to generate any differences, but it is different, so the comparison has some bugs.

Could we make avoid that noise to make comparisons & changelog more reliable?

Kind regards

When using the bump validate command it could make sense to add a --strict flag to enable OpenAPI/AsyncAPI spec verification.

• For OpenAPI we could use
  • The Mermade developed/maintained oas-validator library
  • The AsyncAPI community maintained library @asyncapi/openapi-schema-parser
• For AsyncAPI we could use the “official” community developed library @asyncapi/parser

Nothing to do with this PR, but WDYT of renaming instance into client or httpClient? I find this.client.get more explicit/easy to understand.

Originally posted by @scharrier in #12 (comment)

We want to be able to apply an overlay to an API definition before it's sent to our servers.

At the CLI level, this means adding an overlay method allowing us to get a new version of our definition after applying the overlay:

bump overlay path/to/definition path/to/overlay --out=path/to/destination

If no--out parameter is provided, stdout is used.

We also want to add a parameter to the deploy command:

bump deploy path/to/definition --overlay=path/to/overlay

Which will apply the overlay to the definition just before deploying it on Bump.sh (nothing written on disk, we apply it "in memory" only)

In a near future (this is not part of this issue), we will also add this as an option to our GitHub action, so the code we write here should be usable outside of the CLI (this can be done later).

Questions:

• how do we handle $ref? is there any way to apply the overlay on external dependencies?
• do we want to allow applying an overlay on a components file? if yes, are there some consequencies?

Hi there. I am getting a timeout when trying to compare these two files:
current_api.json
master_api.json

2 feedbacks after using the -- live option (which is really great, btw 👏 ).

• When we launch the preview command with --live, we do not start by generating a preview. We directly get this message:

  Waiting for changes on file /Users/sebastien/Dev/bump/doc/api/v1/openapi.v3.yml...... ⣯
  

  I think that we should start by generating a preview, display the preview URL, and then. wait for changes in the file. As a user, I was expecting something like this:

  * Let's render a preview on Bump... done
  * Your preview is visible at: https://bump.sh/preview/fba0a2c0-cd1d-41c5-9c9d-ab77e52a9ce0 (Expires at 2021-11-11T18:25:11+01:00)
  Waiting for changes on file /Users/sebastien/Dev/bump/doc/api/v1/openapi.v3.yml... ⣯
  

• Also, it may be a good enhancement to display a message each time the file (and the preview) is updated, to inform the user that something is happening. I thought it wasn't working just because nothing new was written in my CLI.

Let's add a CLI option to be able to make the process fail (return code != 0) in case the computed diff returns a breaking change.

Any ideas on the name of the option? --breaking or --ci, other?

Observation

Change needed

comparison instead of comparaison.