Skip to main content

Command frontmatter API

Overview​

Commands are just markdown files, with this comes the use of Content, MDX components and also front-matter.

Here is an example of the command frontmatter you will find in your /commands folder.

/commands/UpdateInventory/index.mdx (example)
---
# id of your command, used for slugs and references in EventCatalog.
id: UpdateInventory

# Display name of the command, rendered in EventCatalog
name: Update inventory

# Version of the command
version: 0.0.3

# Short summary of your command
summary: |
  Command with the intent to update the inventory

# Optional owners, references teams or users
owners:
    - dboyne

# Optional details about the programming language and url for the code
repository:
  language: JavaScript
  url: https://github.com/event-catalog/pretend-shipping-service

# Optional badges, rendered to UI by EventCatalog
badges:
    - content: New service
      backgroundColor: blue
      textColor: blue
      # Optional icon to display (from https://heroicons.com/)
      icon: BoltIcon
---

## Overview

The `Update Inventory` command represents intent to update the inventory of a given item over HTTP.

<NodeGraph />

Required fields​

id​

  • Type: string

Unqiue id of the command. EventCatalog uses this for references and slugs.

Example
---
  id: UpdateInventory
---

name​

  • Type: string

Name of the command this is used to display the name on the UI.

Example
---
  name: Update Inventory
---

version​

  • Type: string

Version of the command.

Example
---
  version: 0.0.1
---

Optional fields​

summary​

Short summary of your command, shown on command summary pages.

Example
---
  summary: |
    Command that updated the inventory over HTTP.
---

owners​

An array of user ids that own the command.

Example
---
  owners:
    - dboyne
    - mSmith
---

badges​

An array of badges that get rendered on the page.

Example
---
  badges:
    - content: My badge
      backgroundColor: blue
      textColor: blue
      # Optional icon to display (from https://heroicons.com/)
      # Or the name of the broker (e.g Kafka, EventBridge, etc)
      icon: BoltIcon
---

specifications​

Added in eventcatalog@2.39.1

You can assign one or more specifications to a command.

Example
---
  specifications:
    - type: asyncapi
      path: order-service-asyncapi.yaml
      name: AsyncAPI Specification
    - type: openapi
      path: openapi.yml
      name: OpenAPI Specification
---
PropertyTypeRequiredDescription
typestringYesThe type of specification, currently only asyncapi and openapi are supported
pathstringYesThe path to the specification file
namestringNoOptional friendly name of the specification, rendered in the UI

Older versions of EventCatalog (< 2.39.0)

If you are using an older version of EventCatalog you will need to use the following syntax.

Example
---
  specifications:
    asyncapiPath: order-service-asyncapi.yaml
    openapiPath: openapi.yml
---

repository​

Added in eventcatalog@2.11.2

Repository language and code url for the command.

Example
---
  repository:
    language: JavaScript
    url: https://github.com/event-catalog/pretend-shipping-service
---
Added in eventcatalog@2.29.3

Configure the event label and message in the docs sidebar.

Example
---
  sidebar:
    badge: POST
    label: Update Inventory
---

visualiser​

Added in eventcatalog@2.39.2

Turn off the visualiser for this resource. This means the resource will not be included in the visualiser or the navigation bar for the visualiser.

Default: true

Example
---
  visualiser: false
---

draft​

Added in eventcatalog@2.48.4

Mark the command as a draft. This will show the command as a draft in the UI.

You can also specify a title and summary for your draft to help you communicate the status of the draft.

/commands/UpdateInventoryStock/index.mdx (example)
---
# Uses the default title and summary to mark things as draft in the UI
draft: true

# Or you can specify a title and summary for your draft
draft: 
  title: "Update Inventory Stock 1.0.1 is in draft"
  # Supports markdown
  message: |
    ### New version of Update Inventory Stock command is in draft

    This is a new version of the Update Inventory Stock command. It is not yet ready for production. We are still working on it and collecting feedback from the team.
    You can use this version in lower environments, **but please be aware that it is still in draft and may change.**
    You can still use a previous version of the command, [Update Inventory Stock 1.0.0](/docs/commands/UpdateInventoryStock/1.0.0), until that version is deprecated.
    _If you would like to provide feedback, please contact us at [feedback@eventcatalog.io](mailto:feedback@eventcatalog.io) or our slack channel [Order Management](https://join.slack.com/t/eventcatalog/shared_invite/zt-1q900000000000000000000000000000)_

---