Service frontmatter API

Overview

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

Here is an example of the service frontmatter you will find in your /services folder.

/services/Orders/index.mdx (example)

---
# id of your service, used for slugs and references in EventCatalog.
id: Orders

# Display name of the Service, rendered in EventCatalog
name: Orders

# Version of the Service
version: 0.0.1

# Short summary of your Service
summary: |
  Service that contains order related information

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

# Optional messages this service receives and it's version
receives:
  - id: InventoryAdjusted
    version: 0.0.3

# Optional messages this service sends and it's version    
sends:
  - id: AddInventory  
    version: 0.0.3

# 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/)
      # Or the name of the broker (e.g Kafka, EventBridge, etc)
      icon: BoltIcon
---

## Overview

This orders service gives API consumers the ability to produce orders in the systems. Events are raised from this system for downstream consumption.

<NodeGraph />

Required fields

id

• Type: string

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

Example

---
  id: Orders
---

name

• Type: string

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

Example

---
  name: My orders service
---

version

• Type: string

Version of the service.

Example

---
  version: 0.0.1
---

Optional fields

summary

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

Example

---
  summary: |
    service that contains everything about orders
---

owners

An array of user ids that own the service.

Example

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

sends

An array of messages (ids) the service sends. These can be commands, queries or events ids.

Example

---
  sends:
    - OrderFulfilled
    - OrderComplete
---

receives

An array of messages (ids) the service receives. These can be commands, queries or events ids.

Example

---
  receives:
    - OrderPlaced
    - OrderAdjusted
---

entities

Added in eventcatalog@2.36.0

An array of entities ids that belong to the this service. Which entities belong to this service.

Example

---
  entities:
    - id: Order
    - id: OrderItem
      # Optional version of the entity, latest version is used if not provided
      version: 0.0.1
---

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/)
      icon: BoltIcon
---

specifications

Added in eventcatalog@2.39.1

You can assign one or more specifications to a service.

Example

---
  specifications:
    - type: asyncapi
      path: order-service-asyncapi.yaml
      name: AsyncAPI Specification
    - type: openapi
      path: openapi.yml
      name: OpenAPI Specification
---

Property	Type	Required	Description
type	string	Yes	The type of specification, currently only asyncapi and openapi are supported
path	string	Yes	The path to the specification file
name	string	No	Optional 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
---

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
---