cli

Check our blog post announcement talking about our new bump diff feature if you missed the v2.1.0 release

🆕 Features

• You can now include Markdown files as an external reference within your contract document with the $ref syntax $ref: "./path/to/local-markdown.md". In the same way you can extract part of your contract (usually JSON schema of your models into dedicated *.yaml or *.json files), you can now extract your markdown content into dedicated files.

  E.g. Your OpenAPI contract api-contract.yml can thus looks like:

  openapi: 3.1.0
  info:
    title: Bump API documentation
    version: 1.0.0
    description:
      $ref: "./docs/introduction.md"
  x-topics:
    - title: Getting started
      content:
        $ref: "./docs/getting-started.md"
    - title: Use cases
      content:
        $ref: "./docs/use-cases.md"
      example:
        $ref: "./docs/use-cases-examples.md"
  servers:
    ...
  paths:
    ...
  

  With files docs/introduction.md, docs/getting-started.md, docs/use-cases.md and docs/use-cases-examples.md right next to your contract document you will be able to generate a comprehensive API documentation with nicely formatted content for your users.

  It's a great new way to include “Topic” sections with hand written content before the documentation of endpoints/webhooks (or channels in case of an AsyncAPI contract) in dedicated Markdown files. Thanks to the x-topics top level property in your contract (As explained in our help page)

Bump markdown syntax

We support common markdown syntax:

• h1, h2, h3, … headers (with ### Title)
• **bold** will render bold
• _italic_ will render italic
• [links](https://bump.sh) will render links
• ̀inline code ̀ will render inline code
• > quotes will render

  quotes

And now all those additional syntax:

• 🆕 ==highlight== will render highlight

• 🆕 ~~strikethrough~~ will render strikethrough

• 🆕 Footnote[^1] will render Footnote[^1]

  [^1]: This is the content of the first footnote

• 🆕 Multiline code blocks with language color syntax highlighting

      ```json
      {
        "hello": "world",
        "number": 1,
        "boolean": true
      }
      ```
  

  Will render

  {
    "hello": "world",
    "number": 1,
    "boolean": true
  }
  

• 🆕 ℹ️ Information call-out

  > info
  >
  > this is an important information to **standout**
  

  will render a blue background information call-out

• 🆕 ✔️ Successfull call-out

  > success
  >
  > This is a *successful* information
  

  will render a green background information call-out

• 🆕 ⚠️ Warning call-out

  > warn
  >
  > This is a *warning* information
  

  will render an orange background information call-out

• 🆕 ❌ Error call-out

  > error
  >
  > This is a *error* information
  

  will render a red background information call-out

🆙 Upgrades

Thanks to @dependabot, all the node dependencies we use are now up-to-date.

Check our blog post announcement talking about our new bump diff feature

This release is focused on a new feature we are launching at Bump: display your API changelog right from your CLI (or Continuous Integration platform).

🆕 Features

• A new command: bump diff FILE_OR_URL. It will let your compare the current version of your Bump.sh documentation with the given file or URL. The command will output on stdout a diff summary and if you call it with the --open flag you will have the visual diff poping up in your browser.

  Here's an example for the Gitlab OpenAPI specifications focused on the latest changes made to their doc/api/openapi/openapi.yaml file:

  • git diff will result in this code diff.

  • And now bump diff:

    $ bump diff --doc gitlab --token <your-bump-private-token> doc/api/openapi/openapi.yaml
    * Let's compare the given definition version... done
    
    Added: DELETE /v4/groups/{id}/access_requests/{user_id}
    Removed: DELETE /v4/groupss/{id}/access_requests/{user_id}
    Added: GET /v4/projects/{id}/access_tokens
    Added: POST /v4/projects/{id}/access_tokens
    Added: DELETE /v4/projects/{id}/access_tokens/{token_id}
    

    Visually, the API changelog for this commit will look like this on Bump.

• You can now use the --open flag within the bump preview command to directly open the preview URL in your browser. That is one click less for you 🤗.

🆙 Upgrades

Thanks to @dependabot, all the node dependencies we use are now up-to-date.

🛠️ Internals

We now export each Command class and TypeScript types within our published NPM package. This is done to be able to integrate the bump-cli package as a library dependency in your own codebase if you need to interact programmatically with Bump. For now it was done mainly to integrate it with our dedicated Github Action. If you have any specific needs, please let us know.

Small release following up the recent 2.0.0 release with:

• 🐛 Bugfix allowing API definition files from filesystem paths with accents characters
• 🆕 Github releases now receives standalone tarballs which can be installed without having npm/node on your machine

Welcome to the new Bump CLI 🎉

It was written with care in Typescript to replace our old ruby gem. Why the change? Mostly because the OpenAPI and AsyncAPI communities have many tools written in Typescript or Javascript and we want to follow their experienced lead. By getting closer to those two world we hope to be able to contribute more too.

Typescript will help us to publish a stable & type safe CLI. On top of that - and especially with the oclif framework - we will be able to publish universal packages for multiple OSes & architectures so everybody can enjoy Bump via command line interface.

Get it while it's hot

npm install -g bump-cli

Enjoy !

• bump preview to build as many API documentation preview as you want.
• bump deploy --dry-run to validate your future API documentation deployment.
• bump deploy to deploy your latest API documentation changes.

🆕 What's new

This new CLI is iso-feature with our old CLI package. However there is one major improvement, we now support recursive external references ($ref keyword in your API specifications), with mixed file or URL access. You can now refactor your API definitions in small chunks, re-use parts of it, and separate concerns between endpoints, models or nested-objects.

Here's a modified example from the official Gitlab API openapi definition:

openapi.yml

openapi: 3.0.0
info:
  description: |
    An OpenAPI definition for the GitLab REST API.
  version: v4
  title: GitLab API

paths:
  # ...

  # ACCESS REQUESTS (PROJECTS)
  /v4/projects/{id}/access_requests:
    $ref: 'v4/access_requests.yaml#/accessRequestsProjects'

  # ...

./v4/access_requests.yaml

accessRequestsProjects:
  get:
    description: Lists access requests for a project
    parameters:
      - name: id
        in: path
    responses:
      '200':
        description: Successful operation
        content:
          application/json:
            $ref: 'models/ProjectAccessResponse.yaml'

./v4/models/ProjectAccessResponse.yaml

schema:
  title: ProjectAccessResponse
  type: object
  properties:
    id:
      type: integer
    usename:
      type: string
example:
  - "id": 1
    "username": "raymond_smith"

Note: we limit the recursion up to a depth of 5. Please contact us if you hit this limit so we can discuss your use-case.

⚠️ Breaking change compared to our old CLI

The old bump validate command has disappeared in favor of a deployment simulation command with bump deploy --dry-run

• Allow custom User-Agent via environment variable #20
• Display documentation public URL after deployment #21
• Send raw definition content to the API #25

Install/update this beta with npm install -g bump-cli@beta ✨

• validate: add a --dry-run flag to the bump deploy command b802020
• deploy: first take to handle bump deploy command 9dcbe95
• preview: first take to handle bump preview command 🎉 cf72a47

Complete changes