⚠️ We are in the process of rewriting the component under thenext
branch. The current version0.X.X
is in the maintenance mode, we are focusing mainly on thenext
branch. Check out releases withnext
suffix in the release tag or thenext
tag on NPM.
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
- Playground
- Web Component
- Development
- Contribution
- Missing features
- Credits
- Contributors
react
(version 16.8.0 or higher)
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:
The list of props for the AsyncAPI React component includes:
-
schema: string | AsyncApiInterface | FetchingSchemaInterface
The
schema
property is required and contains AsyncAPI specification. Use thestring
type, theAsyncApiInterface
type, or theFetchingSchemaInterface
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 theT
type is optional.
For a list and description of features offered by the AsyncAPI React component, see this directory.
To use default styles import them as follows:
import "@asyncapi/react-component/lib/styles/fiori.css";
For information on how to change styles, read the Style Modification document.
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.
If you are not using React you may want to use the @asyncapi/web-component
component as a plain web component in any other web framework of your choice or as an element of a static HTML webpage. This is achieved by making use of web-react-components.
When invoked as an independent entity, Web Component takes the following props (as it is still a React component):
schema
is aschema
property from the React component,NOTE: Since version 0.19.0 specifying a
schema
object can be omitted.schema.url
andschema.requestOptions
can be replaced withschemaUrl
andschemaFetchOptions
properties accordingly.config
is an optionalconfig
property from the React component,schemaUrl
property is astring
, specific to Web Component, containing a URL to fetch an AsyncAPI Schema from. It is a wrapper forschema.url
property inschema
object under the hood,NOTE: If
schemaUrl
property is specified, theschema.url
property of the React component will be ignored.schemaFetchOptions
property is an optionalobject
of RequestInit type in JSON format, specific to Web Component, containing additional fetching options. It is a wrapper forschema.requestOptions
property inschema
object, which are both needed only in case process of fetching from a URL is any different from a usual browser request,NOTE: If
schemaFetchOptions
property is specified,schema.requestOptions
property of the React component will be ignored. IfschemaUrl
property is NOT specified,schemaFetchOptions
will be ignored itself andschema.url
/schema.requestOptions
properties of the React component must be used in this case.cssImportPath
property is the path to styles. Default version fromunpkg.com
contains guaranteed minimum styling for the Web Component,- webcomponentsjs is a series of polyfills to make code runnable in old browsers. It is optional if you do not intend to support any.
<!-- Remove 'webcomponentsjs' if no support for older browsers is required -->
<script src="https://unpkg.com/@webcomponents/[email protected]/webcomponents-bundle.js"></script>
<script src="https://unpkg.com/@asyncapi/[email protected]/lib/asyncapi-web-component.js" defer></script>
<asyncapi-component
schemaUrl="https://raw.githubusercontent.com/asyncapi/asyncapi/master/examples/2.0.0/streetlights.yml"
schemaFetchOptions='{"method":"GET","mode":"cors"}' <!-- Remove if it is only a plain browser request -->
cssImportPath="https://unpkg.com/@asyncapi/[email protected]/lib/styles/fiori.css">
</asyncapi-component>
NOTE: If a Web Component is called with no properties at all, error will be shown on page.
NOTE: If there are several Web Components on one page, each one will be rendered using its own properties.
Run this command to install the component in your project:
npm install --save @asyncapi/web-component
Check out this simple sandbox application that uses the Web Component in Angular project:
To use component in Angular, follow these steps:
- Update
AppModule
by adding theCUSTOM_ELEMENTS_SCHEMA
to theschemas
array in theNgModule
metadata:
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
@NgModule({
...
schemas: [
CUSTOM_ELEMENTS_SCHEMA,
]
})
export class AppModule {}
- Import the
@asyncapi/web-component
module in an Angular's component where you want to use the web component:
import { Component } from '@angular/core';
import '@asyncapi/web-component/lib/asyncapi-web-component';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.css']
})
export class AppComponent {
...
}
- Use web component in the template as follows:
<asyncapi-component
[schema]="schema"
[config]="config"
[schemaUrl]="schemaUrl"
[schemaFetchOptions]="schemaFetchOptions"
[cssImportPath]="cssImportPath">
</asyncapi-component>
where:
schema
,config
,schemaUrl
,schemaFetchOptions
are Web Component's properties used in any valid combination, as described in Web Component specification,cssImportPath
is the path to styles. By default it isassets/fiori.css
NOTE: The easiest way to use the default css is to copy the content of the
@asyncapi/react-component/lib/styles/fiori.css
file to aassets/asyncapi.css
file.
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.
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.
See the list of features that are still missing in the component:
- render
bindings
- render
tags
- render
externalDocs
- render
schema properties
- render
correlationID
If you want to help us develop them, feel free to contribute.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!