event-catalog / eventcatalog

An open source documentation tool to bring discoverability to your event-driven architectures
https://eventcatalog.dev
MIT License
1.58k stars 132 forks source link

Document usage of HTTP API endpoints #523

Open floriankraemer opened 1 month ago

floriankraemer commented 1 month ago

Have you read the Contributing Guidelines on issues?

Description

Introduce a new usesEndpoints property in a service that will be used to generate a list and diagram of endpoints of other services used by this service. The 1st level will be the name of the service it will call and the 2nd level will describe the OpenAPI "operationId".

operationId is an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API.

Part of the service description:

usesEndpoints:
  - <ServiceName>
    - <operationId>
  - Users
    - deleteUser
    - addUser

Ideally we could also render a map of all cross references between services, a complete map, similar to this https://observablehq.com/@d3/force-directed-tree?intent=fork when viewing a service page.

image

I assume this is relatively easy to build because it just adds a new two level deep array to the already existing service data. So it would require just some data transformation and extraction from the schema to output the data for d3.js hat then could visualize it in a widget on the service page.

Motivation

We want to understand and visualize our existing HTTP API calls between services.