Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/asyncapi/asyncapi-react

React component for rendering documentation from your specification in real-time in the browser. It also provides a WebComponent and bundle for Angular and Vue
https://github.com/asyncapi/asyncapi-react

asyncapi asyncapi-specification event get-global-node-release-workflows hacktoberfest nodejs react reactjs

Last synced: about 2 months ago
JSON representation

React component for rendering documentation from your specification in real-time in the browser. It also provides a WebComponent and bundle for Angular and Vue

Awesome Lists containing this project

README

        

[![AsyncAPI React Component](./.github/assets/logo.png)](https://www.asyncapi.com)

React component for AsyncAPI specification. Available also as a Web Component, but not only.

![npm](https://img.shields.io/npm/dt/@asyncapi/react-component) [![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-908a85?logo=gitpod)](https://gitpod.io/#https://github.com/asyncapi/asyncapi-react/tree/next)

## Overview

The official [React](https://reactjs.org/) component for AsyncAPI 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.

- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Using in React](#using-in-react)
- [Using in other technologies](#using-in-other-technologies)
- [Props](#props)
- [Features](#features)
- [Styles](#styles)
* [Default styles](#default-styles)
* [Custom styles](#custom-styles)
* [Custom logo](#custom-logo)
- [Playground](#playground)
- [Modules](#modules)
- [Development](#development)
- [Contribution](#contribution)
- [Credits](#credits)
- [Contributors](#contributors)

## Prerequisites

- [`react`](https://github.com/facebook/react/) (version 16.8.0 or higher)

## Installation

Run this command to install the component in your project:

```sh
npm install --save @asyncapi/react-component
```

Check out this sandbox application that uses the React component:

[![Edit asyncapi-react-component-in-action](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/asyncapi-react-component-in-action-wvdy2)

## Using in React

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

```tsx
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 = () => ;

render(, 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](./docs/usage/angular.md)
- [Using in Vue](./docs/usage/vue.md)
- [Using in NextJS](./docs/usage/nextjs.md)
- [Standalone bundle usage](./docs/usage/standalone-bundle.md)
- [Web Component usage](./docs/usage/web-component.md)

## 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`](https://github.com/asyncapi/parser-js/blob/master/lib/models/asyncapi.js) type, parsed specification as JS object from [AsyncAPI Parser](https://github.com/asyncapi/parser-js) or the [`FetchingSchemaInterface`](./library/src/types.ts#L393) 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](https://github.com/asyncapi/asyncapi#asyncapi-specification).

- **config?: Partial**

The `config` property is optional and contains configuration for the AsyncAPI component. For more information on the available configuration options, read the [Configuration Modification](./docs/configuration/config-modification.md) document.
This property is concatenated with the [default configuration](./library/src/config/default.ts).

> **NOTE:** The `Partial` 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](./docs/features) directory.

## Styles

### Default styles
To use default styles import them as follows:

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

### Custom styles
The AsyncAPI React component does not set any global fonts. This component allows the usage of your custom `font-family` and other styling.

This can be done by defining the styles in a file or inline using a `` tag in the `<head>` section of the page where you are using AsyncAPI React component.

Example custom styles (defined in the `styles/custom.css` file):
```css
html {
-moz-tab-size: 4;
-o-tab-size: 4;
tab-size: 4;
line-height: 1.15;
-webkit-text-size-adjust: 100%;
}

body {
margin: 0;
font-family: system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji;
}
```

If you are using the component in a project that uses a bundler like Webpack, don't forget to import the custom styles.

``` js
import "styles/custom.css";
import "@asyncapi/react-component/styles/default.min.css";
```

If you are using the [standalone bundle](./docs/usage/standalone-bundle.md), you can put the custom styles as a style sheet link or as an inline style in the `<head>` section of the HTML code:

```html
<head>
<!-- Custom style sheet -->
<link rel="stylesheet" href="./styles/custom.css">

<!-- OR as inline style -->
<style>
html{-moz-tab-size:4;-o-tab-size:4;tab-size:4;line-height:1.15;-webkit-text-size-adjust:100%};
body{margin:0;font-family:system-ui,-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif,Apple Color Emoji,Segoe UI Emoji};




...

```

### Custom logo

The AsyncAPI component supports the option to use a custom logo. By using the `x-logo` custom extension in the [InfoObject](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#infoObject), a logo will be shown in the top left corner.

> **NOTE**: The logo will only appear if the [sidebar option](./docs/configuration/config-modification.md#definition) is enabled.

```yaml
asyncapi: 2.2.0
info:
title: Account Service
version: 1.0.0
description: This service is in charge of processing user signups.
x-logo: 'https://raw.githubusercontent.com/asyncapi/spec/master/assets/logo.png'
channels:
...
```

## Playground

This repository comes in with a [Playground application](https://asyncapi.github.io/asyncapi-react/). 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](./docs/development/guide.md#install-dependencies) 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`](https://github.com/facebook/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](https://github.com/facebook/react/tree/master/packages/react) and [ReactDOM](https://github.com/facebook/react/tree/master/packages/react-dom) 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](https://github.com/asyncapi/parser-js) 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](./docs/development/guide.md).

## 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`](CONTRIBUTING.md) document.

If you have a bug to report, reproduce it in an online code editor. For example, use [CodeSandbox](https://codesandbox.io/). 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](https://kyma-project.io/), in 2019 it was moved under AsyncAPI Initiative.

## Contributors

Thanks goes to these wonderful people ([emoji key](https://github.com/all-contributors/all-contributors#emoji-key)):



Maciej UrbaΕ„czyk
Maciej UrbaΕ„czyk

πŸ’» πŸ“– πŸ€” 🚧 πŸ‘€ ⚠️ πŸš‡ πŸ› πŸ’‘
Karolina Zydek
Karolina Zydek

πŸ“– πŸ‘€ 🚧
Agata
Agata

πŸ’» 🚧
Lukasz Gornicki
Lukasz Gornicki

πŸ“– πŸ’‘ πŸ€” πŸ’» πŸš‡ πŸ› πŸ“ 🚧
Mateusz PuczyΕ„ski
Mateusz PuczyΕ„ski

πŸ’» πŸ“– πŸ€” 🚧 πŸ‘€ ⚠️
Hesyar Uzuner
Hesyar Uzuner

πŸ› πŸ’»
Marcus Ilgner
Marcus Ilgner

πŸ› πŸ’»


Dominik Henneke
Dominik Henneke

πŸ’»
Oliver Sand
Oliver Sand

πŸ’»
Jakub Iwanowski
Jakub Iwanowski

πŸ’»
depimomo
depimomo

⚠️
Sanskar Patro
Sanskar Patro

πŸ’»
danielchu
danielchu

πŸš‡
Fran MΓ©ndez
Fran MΓ©ndez

πŸ’» 🚧


Claude Gex
Claude Gex

πŸ’» πŸ“¦ πŸ€”
c-pius
c-pius

πŸ’» πŸ›
Viacheslav Turovskyi
Viacheslav Turovskyi

πŸ“– πŸ’»
195858
195858

πŸ’»
Aayush Kumar Sahu
Aayush Kumar Sahu

πŸ’»
Dale Lane
Dale Lane

πŸ’» πŸ€”
Michal Gornicki
Michal Gornicki

πŸ“–


Samriddhi
Samriddhi

πŸ’»
W0nderMuffin
W0nderMuffin

πŸ’»
Andrea Falzetti
Andrea Falzetti

πŸ’»
Dominik Schwank
Dominik Schwank

πŸ’»
Kai Szybiak
Kai Szybiak

πŸ’»
Ludovic Dussart
Ludovic Dussart

πŸ’»
Heiko Henning
Heiko Henning

πŸ’»


thim81
thim81

πŸ’»
Marcelo Avancini
Marcelo Avancini

πŸ’»
Sergey Shishkin
Sergey Shishkin

πŸ’»
Takakazu Fu
Takakazu Fu

πŸ’»
Jan
Jan

πŸ’»
Ace
Ace

πŸ’»
Jonas Lagoni
Jonas Lagoni

πŸ’»

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!