@asyncapi/react-component

React Component

React component for AsyncAPI 2.0 specification. Available also as a Web Component.

Overview

A official React component for AsyncAPI 2.0 specification. It allows you to render the documentation of your asynchronous API provided in the AsyncAPI specification format and validate this specification. You can fully restyle the component using your own styles.

CAUTION: This package only supports AsyncAPI 2.0 specification. If you use 1.x, we recommend that you upgrade to the latest AsyncAPI version using the Node.js or Go converters.

• Prerequisites
• Installation
• Using in React
• Using in other technologies
• Props
• Features
• Styles
• Playground
• Modules
• Development
• Contribution
• Credits
• Contributors

Prerequisites

• react (version 16.8.0 or higher)

Installation

Run this command to install the component in your project:

npm install --save @asyncapi/react-component

Check out this simple sandbox application that uses the React component:

Using in React

Check a simple example which shows passing the inline AsyncAPI specification with custom configurations:

import * as React from "react";
import { render } from "react-dom";
import AsyncApiComponent, { ConfigInterface } from "@asyncapi/react-component";

const schema = `
asyncapi: '2.0.0'
info:
  title: Example
  version: '0.1.0'
channels:
  example-channel:
    subscribe:
      message:
        payload:
          type: object
          properties:
            exampleField:
              type: string
            exampleNumber:
              type: number
            exampleDate:
              type: string
              format: date-time
`;

const config: ConfigInterface = {
  schemaID: 'custom-spec',
  show: {
    operations: false,
    errors: false,
  },
};

const App = () => <AsyncApiComponent schema={schema} config={config} />;

render(<App />, document.getElementById("root"));

Using in other technologies

To check how to use web-component or use a component in other technologies see:

• Using in Angular
• Using in Vue
• Using in NextJS
• Web Component usage

Props

The list of props for the AsyncAPI React component includes:

• schema: string | AsyncAPIDocument | object | FetchingSchemaInterface

  The schema property is required and contains AsyncAPI specification. Use the string type, the AsyncAPIDocument type, parsed specification as JS object from AsyncAPI Parser or the FetchingSchemaInterface object to fetch the schema from an external resource. For more information on what it contains and what it should look like, read AsyncAPI Specification.

• config?: Partial<ConfigInterface>

  The config property is optional and contains configuration for the AsyncAPI component. For more information on the available configuration options, read the Configuration Modification document. This property is concatenated with the default configuration.

  NOTE: The Partial<T> type means that every field in the T type is optional.

Features

For a list and description of features offered by the AsyncAPI React component, see this directory.

Styles

To use default styles import them as follows:

import "@asyncapi/react-component/styles/default.css";
// or minified version
import "@asyncapi/react-component/styles/default.min.css";

Playground

This repository comes in with a Playground application. Test it to see the component in action and play with it before you use it in your application.

You can also run the Playground application locally by following this instruction from the development guide.

Modules

The @asyncapi/react-component package has 3 crafted JS modules to be used in various environments:

• esm (ECMAScript Modules) is intended for use in a single-page applications with predefined environments like create-react-app that are capable of resolving dependencies (via Webpack, Browserify, etc). It can also be used on the server side (for tasks like Server Side Rendering) when the application is using esm.
• cjs (CommonJS Modules) similar uses as for esm modules, but using CommonJS modules.
• umd (Universal Module Definition) is a dependency-free module that includes everything you need to serve AsyncAPI documentation (however React and ReactDOM dependencies must be served separately) on a single-page application that can't resolve npm module dependencies or in normal HTML page. We have 2 types of minified umd bundles, with and without AsyncAPI Parser in paths:
  • @asyncapi/react-component/browser/index.js
  • @asyncapi/react-component/browser/without-parser.js

Development

For information on how to set up a development environment, write and run tests, follow the naming and architecture convention defined for the project in the Development Guide.

Contribution

If you have a feature request, add it as an issue or propose changes in a pull request (PR). If you create a feature request, use the dedicated Feature request issue template. When you create a PR, follow the contributing rules described in the CONTRIBUTING.md document.

If you have a bug to report, reproduce it in an online code editor. For example, use CodeSandbox. Attach the link to the reproduced bug to your issue. Log the bug using the Bug report template.

Credits

The project was originally developed under the Kyma project, in 2019 it was moved under AsyncAPI Initiative.

Contributors

Thanks goes to these wonderful people (emoji key):

Maciej Urbańczyk 💻 📖 🤔 🚧 👀 ⚠️ 🚇 🐛 💡	Karolina Zydek 📖 👀 🚧	Agata 💻 🚧	Lukasz Gornicki 📖 💡 🤔 💻 🚇 🐛 📝 🚧	Mateusz Puczyński 💻 📖 🤔 🚧 👀 ⚠️	Hesyar Uzuner 🐛 💻	Marcus Ilgner 🐛 💻
Dominik Henneke 💻	Oliver Sand 💻	Jakub Iwanowski 💻	depimomo ⚠️	Sanskar Patro 💻	danielchu 🚇	Fran Méndez 💻 🚧
Claude Gex 💻 📦 🤔	c-pius 💻 🐛	Viacheslav Turovskyi 📖 💻

This project follows the all-contributors specification. Contributions of any kind welcome!