@asyncapi/parser

What is @asyncapi/parser?

@asyncapi/parser is a powerful npm package designed to parse AsyncAPI documents. It allows developers to read, validate, and manipulate AsyncAPI specifications programmatically. This is particularly useful for generating documentation, creating mock servers, and integrating with other tools in the API development lifecycle.

What are @asyncapi/parser's main functionalities?

Parsing AsyncAPI Documents

This feature allows you to parse an AsyncAPI document from a JSON string. The parsed document can then be used for further processing or validation.

const { Parser } = require('@asyncapi/parser');
const parser = new Parser();
const asyncapiDocument = `{
  "asyncapi": "2.0.0",
  "info": {
    "title": "Streetlights API",
    "version": "1.0.0"
  },
  "channels": {
    "light/measured": {
      "description": "Channel for light measurement events",
      "subscribe": {
        "summary": "Receive light measurement events",
        "message": {
          "$ref": "#/components/messages/LightMeasured"
        }
      }
    }
  },
  "components": {
    "messages": {
      "LightMeasured": {
        "payload": {
          "type": "object",
          "properties": {
            "lumens": {
              "type": "integer"
            }
          }
        }
      }
    }
  }
}`;
parser.parse(asyncapiDocument)
  .then(doc => console.log('Parsed document:', doc))
  .catch(err => console.error('Error parsing document:', err));

Validating AsyncAPI Documents

This feature allows you to validate an AsyncAPI document after parsing it. It checks for any schema violations or inconsistencies in the document.

const { Parser } = require('@asyncapi/parser');
const parser = new Parser();
const asyncapiDocument = `{
  "asyncapi": "2.0.0",
  "info": {
    "title": "Streetlights API",
    "version": "1.0.0"
  },
  "channels": {
    "light/measured": {
      "description": "Channel for light measurement events",
      "subscribe": {
        "summary": "Receive light measurement events",
        "message": {
          "$ref": "#/components/messages/LightMeasured"
        }
      }
    }
  },
  "components": {
    "messages": {
      "LightMeasured": {
        "payload": {
          "type": "object",
          "properties": {
            "lumens": {
              "type": "integer"
            }
          }
        }
      }
    }
  }
}`;
parser.parse(asyncapiDocument)
  .then(doc => {
    const validationErrors = doc.validate();
    if (validationErrors.length) {
      console.error('Validation errors:', validationErrors);
    } else {
      console.log('Document is valid');
    }
  })
  .catch(err => console.error('Error parsing document:', err));

Accessing Document Components

This feature allows you to access various components of the parsed AsyncAPI document, such as channels and messages. This is useful for generating documentation or creating mock servers.

const { Parser } = require('@asyncapi/parser');
const parser = new Parser();
const asyncapiDocument = `{
  "asyncapi": "2.0.0",
  "info": {
    "title": "Streetlights API",
    "version": "1.0.0"
  },
  "channels": {
    "light/measured": {
      "description": "Channel for light measurement events",
      "subscribe": {
        "summary": "Receive light measurement events",
        "message": {
          "$ref": "#/components/messages/LightMeasured"
        }
      }
    }
  },
  "components": {
    "messages": {
      "LightMeasured": {
        "payload": {
          "type": "object",
          "properties": {
            "lumens": {
              "type": "integer"
            }
          }
        }
      }
    }
  }
}`;
parser.parse(asyncapiDocument)
  .then(doc => {
    const channels = doc.channels();
    console.log('Channels:', channels);
    const messages = doc.components().messages();
    console.log('Messages:', messages);
  })
  .catch(err => console.error('Error parsing document:', err));

Other packages similar to @asyncapi/parser

swagger-parser

swagger-parser is a powerful npm package for parsing, validating, and dereferencing Swagger (OpenAPI) documents. It offers similar functionalities to @asyncapi/parser but is focused on the OpenAPI specification. It is widely used for working with RESTful APIs.

openapi-schema-validator

openapi-schema-validator is a package designed to validate OpenAPI 3.0 schemas. While it does not offer parsing capabilities, it provides robust validation features similar to those found in @asyncapi/parser.

openapi-types

openapi-types is a TypeScript library that provides type definitions for OpenAPI specifications. It is useful for developers who want to ensure type safety when working with OpenAPI documents, similar to how @asyncapi/parser provides structure for AsyncAPI documents.

README

JS Parser

Parse and validate AsyncAPI documents

---

:loudspeaker: ATTENTION:

This package is under development and it has not reached version 1.0.0 yet, what means its API might change without prior notice. Once it reaches its first stable version, we'll follow semantic versioning.

---

Use this package to parse and validate AsyncAPI documents —either YAML or JSON— in your Node.js or browser application. Updated bundle for the browser is always attached to the GitHub Release.

This package doesn't support AsyncAPI 1.x.

Install

npm install @asyncapi/parser

API

Check out the API page.

Examples

Example passing inline AsyncAPI

const parser = require('@asyncapi/parser');

const doc = await parser.parse(`
  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
`);

console.log(doc.info().title());
// => Example

Example passing a URL

const parser = require('@asyncapi/parser');

const doc = await parser.parseUrl('https://my.server.com/example-asyncapi.yaml');

console.log(doc.info().title());
// => Example

Example using OpenAPI schemas

Head over to asyncapi/openapi-schema-parser for more information.

Example using RAML data types

Head over to asyncapi/raml-dt-schema-parser for more information.

Develop

1. Run tests with npm test
2. Write code and tests.
3. Make sure all tests pass npm test
4. Generate new API docs npm run docs
5. Update bundle for client-side parser npm run bundle

Contributing

Read CONTRIBUTING guide.