Skip to main content

OpenAPI Specifications

Added in eventcatalog@2.6.0

Services in EventCatalog allow you to render OpenAPI specifications (see demo).

Example

You have two options for adding OpenAPI specifications to your service:

Why not automate your EventCatalog from your OpenAPI files?

Did you know you can automate your documentation, visualizations and owners using your OpenAPI Files?

We have a OpenAPI plugin that can generate your catalog from your OpenAPI files, transforming your operations into commands, queries and events. You can assign these to services and domains and much more...

Adding OpenAPI files to EventCatalog​

This option is useful if you want to keep your OpenAPI files in your EventCatalog.

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)

Then you need to reference the file in the service frontmatter.

example: /services/Orders/index.mdx
---
  specifications:
    - type: openapi
      # Path to the OpenAPI file relative to the service directory
      path: openapi.yml
      # Friendly name for the specification
      name: OpenAPI Specification
---

Reference the OpenAPI file from a remote URL​

Added in eventcatalog@2.61.2

This can be useful if you want to keep your OpenAPI files in a remote repository and render them in EventCatalog.

The pages will be built at build time, so the URL needs to be accessible by the build machine.

If your specifications changes you need to rebuild your EventCatalog as the pages are built at build time.

example: /services/Orders/index.mdx
---
  specifications:
    - type: openapi
      # Path to the OpenAPI file from a remote URL (accessible by the build machine)
      path: https://raw.githubusercontent.com/event-catalog/generator-openapi/refs/heads/main/examples/product-api/openapi.yml
      # Friendly name for the specification
      name: Product API
---

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