cli

🆕 diff command now accepts a --format argument

• The bump diff command now accepts a --format argument to be able to return three different format diff outputs:
  • text will return the current default format
  • markdown will return a markdown formatted diff
  • json will return a list of json objects with all the details of the diff

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.

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