Skip to main content

GraphQL schemas

Added in eventcatalog@2.6.0

Services in EventCatalog allow you to render GraphQL schemas (see demo).

Example

You have two options for adding GraphQL schemas to your service:

Why not automate your EventCatalog from your GraphQL files?

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

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

Adding GraphQL files to EventCatalog​

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

To add a GraphQL schema to your service you will need to include the file itself inside the service directory.

  • /services/{Service Name}/graphql.schema
    • (example /services/Orders/graphql.schema)

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

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

Reference the GraphQL file from a remote URL​

Added in eventcatalog@2.61.2

This can be useful if you want to keep your GraphQL 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 schemas changes you need to rebuild your EventCatalog as the pages are built at build time.

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

Multiple GraphQL Files​

Added in eventcatalog@2.39.1

You can also assign multiple GraphQL 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: graphql
      path: graphql-v1.schema
      name: v1
    - type: graphql
      path: graphql-v2.schema
      name: v2
---

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

Example