Skip to main content

Adding specifications to services

You can assign OpenAPI and AsyncAPI specifications to your services in EventCatalog.

Example

When you assign a specification to the service your users will be able to view, read and download the specification files.

You can view a demo of a service with many specification files here.

Adding OpenAPI specification files​

Added in eventcatalog@2.6.0

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

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)

In this example we will look at assigning a single OpenAPI file and multiple OpenAPI files to a service.

Single OpenAPI File​

You can assign a single OpenAPI file to a service by adding the following frontmatter to your service.

example: /services/Orders/index.mdx
---
  specifications:
    - type: openapi
      path: openapi.yml
      name: OpenAPI Specification
---

This will render a new badge on your page and a new button to load the OpenAPI page for your service.

Example

Multiple OpenAPI Files​

Added in eventcatalog@2.39.1

You can also assign multiple OpenAPI files to a single service.

This can be useful if your service exposes multiple APIs or versions of the same API.

example: /services/Orders/index.mdx
---
  specifications:
    - type: openapi
      path: openapi-v1.yml
      name: v1
    - type: openapi
      path: openapi-v2.yml
      name: v2
---

This will render a list of specification files on your service page and navigation bar.

Example

Viewing specification files​

When you click on a specification file in the list it will render the specification file in the main content area.

Example

Automate your EventCatalog from your OpenAPI files

Did you know you can use the OpenAPI generator to generate your EventCatalog? Check out the OpenAPI integration for more information.

Adding AsyncAPI specification files​

Added in eventcatalog@2.6.0

Services in EventCatalog allow you to render AsyncAPI specifications files.

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

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

Next add the specifications frontmatter API to your service.

Example
---
  specifications:
    asyncapiPath: asyncapi.yml
---

In this example we will look at assigning a single AsyncAPI file to a service.

Single AsyncAPI File​

You can assign a single AsyncAPI file to a service by adding the following frontmatter to your service.

Example
---
  specifications:
    - type: asyncapi
      path: asyncapi.yml
      name: AsyncAPI Specification
---

Example

Multiple AsyncAPI Files​

Added in eventcatalog@2.39.1

You can also assign multiple AsyncAPI files to a single service.

This can be useful if your service exposes multiple APIs or versions of the same API.

Example
---
  specifications:
    - type: asyncapi
      path: asyncapi-v1.yml
      name: v1
    - type: asyncapi
      path: asyncapi-v2.yml
      name: v2
---

This will render a list of specification files on your service page and navigation bar.

Automate your EventCatalog from your AsyncAPI files

Did you know you can use the AsyncAPI generator to generate your EventCatalog? Check out the AsyncAPI integration for more information.