Skip to content
This repository has been archived by the owner on Apr 11, 2024. It is now read-only.

A library that focuses on finding and analyzing the relationships between AsyncAPI documents. It outputs a map of the system architecture. Except for a default map, it is possible to get output as mermaid.js flow diagram, PlantUML class diagram and more to come.

License

Notifications You must be signed in to change notification settings

asyncapi-archived-repos/cupid

Repository files navigation

AsyncAPI Cupid

Github license PR testing - if Node project npm Coverage Status

Overview

An official library that focuses on finding and analyzing the relationships between AsyncAPI files to later output consolidated information about the system architecture. Output format would be customizable and available in different formats like PlantUML, mermaid.js, ReactFlow.

Install

npm install @asyncapi/cupid

Technical Details

This library takes AsyncAPI files as an array input for which the user wants to discover the relations between them. It then validates and parses the given array of AsyncAPI files and generates the output in desired passed syntax. In the process, for every different server, it assigns a slug having the server's URL and protocol and then maps channels with the same server. Following, it maps the service information with the channel's name as per if the service is subscribing/publishing to a given channel. The sub/pub Map of default output syntax provides the service name and the metadata of the service including but not limited to description, payload, headers, bindings, extensions.

API Documentation

See API documentation for more example and full API reference information.

Usage

Node.js

const cupid = require('@asyncapi/cupid');
const path = require('path');
const fs = require('fs');

async function getAsyncApiExamples() {
  const docs = [];
  const files = [
    ...
  ]
  for (const file of files) {
    const asyncApiDoc = fs.readFileSync(file, 'utf8');
    docs.push(asyncApiDoc);
  }
  try {
    const mermaidFlowchart = await cupid.getRelations(docs,{syntax:'mermaid'});
    console.log(mermaidFlowchart);
  } catch (error) {
    console.error(error);
  }
}
getAsyncApiExamples();

// For default output syntax
const defaultOutput = cupid.getRelations(docs);

// For mermaid Flowchart 
const mermaidFlowchart = cupid.getRelations(docs,{syntax:'mermaid'});

// For plantUML classDiagram 
const plantUMLClassDiagram = cupid.getRelations(docs,{syntax:'plantUML'});

// For reactFlow nodes
const reactFlowNodes = cupid.getRelations(docs,{syntax:'reactFlow'});

Default Output Syntax

Map(n) {
  '<server1>' => Map(m) {
    'channel1' => { sub: [Map(1) {"<Service Name>" => "<metadata>"}, ...], pub: [[Map(1) {"<Service Name>" => "<metadata>"}, ...] },
    'channel2' => { sub: [[Map(1) {"<Service Name>" => "<metadata>"}, ...], pub: [[Map(1) {"<Service Name>" => "<metadata>"}, ...] }
  }
}

Mermaid Flowchart

Syntax

Based on Flight Notification Service example.

graph TD
 server1[(mqtt://localhost:1883)]
FlightMonitorService[Flight Monitor Service]
FlightMonitorService -- flight/update --> server1
FlightNotifierService[Flight Notifier Service]
server1 -- flight/update --> FlightNotifierService
FlightSubscriberService[Flight Subscriber Service]
FlightSubscriberService -- flight/queue --> server1
server1 -- flight/queue --> FlightMonitorService

Flowchart

Mermaid Flowchart

View in online editor

PlantUML classDiagram

Syntax

Based on FlightService example.

@startuml
title Classes - Class Diagram

class server1 { 
 url: mqtt://localhost:1883 
 protocol: mqtt
}
FlightMonitorService --|> server1:flight/update
server1 --|> FlightNotifierService:flight/update
FlightSubscriberService --|> server1:flight/queue
server1 --|> FlightMonitorService:flight/queue
@enduml

ClassDiagram

PlantUML classDiagram

View in online editor

React Flow Nodes

Syntax

Based on FlightService example.

[
  {
    id: 'Server1',
    data: { label: 'mqtt://localhost:1883,mqtt' },
    position: { x: 250, y: 5 }
  },
  {
    id: 'FlightMonitorService',
    data: { label: 'Flight Monitor Service' },
    position: { x: 100, y: 10 }
  },
  {
    id: 'edge1',
    source: 'FlightMonitorService',
    target: 'Server1',
    animated: true,
    label: 'flight/update',
    type: 'edgeType',
    arrowHeadType: 'arrowclosed'
  },
  {
    id: 'FlightNotifierService',
    data: { label: 'Flight Notifier Service' },
    position: { x: 100, y: 10 }
  },
  {
    id: 'edge2',
    source: 'Server1',
    target: 'FlightNotifierService',
    animated: true,
    label: 'flight/update',
    type: 'edgeType',
    arrowHeadType: 'arrowclosed'
  },
  {
    id: 'FlightSubscriberService',
    data: { label: 'Flight Subscriber Service' },
    position: { x: 100, y: 10 }
  },
  {
    id: 'edge3',
    source: 'FlightSubscriberService',
    target: 'Server1',
    animated: true,
    label: 'flight/queue',
    type: 'edgeType',
    arrowHeadType: 'arrowclosed'
  },
  {
    id: 'edge4',
    source: 'Server1',
    target: 'FlightMonitorService',
    animated: true,
    label: 'flight/queue',
    type: 'edgeType',
    arrowHeadType: 'arrowclosed'
  }
]

React Flow Nodes

reactFlow Nodes

Steps to visualize relations in React Flow

  1. Setup a react project in which you want to display reactFlow nodes.
  2. Install @asyncapi/cupid into the project.
  3. Make a react component for the example.

Example

import React from 'react';
import ReactFlow from 'react-flow-renderer';
import cupid from '@asyncapi/cupid';
import {getAsyncApiExamples} from './utils'; // function for reading AsyncAPI files

const docs = getAsyncApiExamples();
const elements = cupid.getRelations(docs,{syntax:'reactFlow'});

export default () => (
  <div style={{ height: 300 }}>
    <ReactFlow elements={elements} />
  </div>
);

Develop

  1. Clone the project git clone https://github.com/asyncapi/cupid.git
  2. Install the dependencies npm i
  3. For a quick overview you can run tests by npm test. You can also contribute to provide more different syntax outputs to visualize the relations.
  4. Write code and tests.
  5. Make sure all tests pass npm test
  6. Make sure code is well formatted and secure npm run lint

Contributing

Read CONTRIBUTING guide.

About

A library that focuses on finding and analyzing the relationships between AsyncAPI documents. It outputs a map of the system architecture. Except for a default map, it is possible to get output as mermaid.js flow diagram, PlantUML class diagram and more to come.

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks