Skip to main content

Creating services

Adding a service to your Catalog is a great way for you to document your service and define which messages it receives or sends.

What do services look like in EventCatalog?​

Example

Adding a new service​

To add a new service create a new folder within the /services folder with an index.md file.

  • /services/{Service Name}/index.md
    • (example /services/Orders/index.md)

The index.md contents are split into two sections, frontmatter and the markdown content.

Here is an example of what a domain markdown file may look like.

/services/Orders/index.md (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 badges, rendered to UI by EventCatalog
badges:
    - content: New service
      backgroundColor: blue
      textColor: blue
---

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

That's it!

Once you add your new service to EventCatalog, it will now show in the docs, visualizer and discoverability table.

Adding content​

With services you can write any Markdown you want and it will render on your page. Every service gets its own page.

Within your markdown content you can use components to add interactive components to your page.

Adding OpenAPI​

Services in EventCatalog allow you to render OpenAPI specification files or schemas on the page.

Add OpenAPI spec file​

To add an OpenAPI file to your service you will need to include the file itself inside the service directory.

  • /services/{Service Name}/openapi.yml
    • (example /services/Orders/openapi.yml)

Next include the <OpenAPI/> component inside your markdown file.

...

This is my awesome service.

<!-- This will load the OpenAPI document in your service and create a link in the side navigation to view it. -->
<OpenAPI/>

...

Tips for service content​

It's entirely up to you what you want to add to your services markdown content but here are a few things you might want to consider.

  • Context of the service. What is it? Why does it exist?
  • How others can understand who owns this service?
  • How others can interact with the service? What spec files or schemas will you document?
  • Any edit/contributing guidelines?