@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.

Custom message parsers

AsyncAPI doesn't enforce one schema format for messages. You can have payload of your messages described with OpenAPI, Avro, etc. This parser by default parses only AsyncAPI schema format. You can extend it by creating a custom parser and registering it withing the parser:

1. Create custom parser module that exports two functions:

   module.exports = {
     parse: ({ message, defaultSchemaFormat }) => { //custom parsing logic},
     getMimeTypes: () => [
       '//mime types that will be used as the `schemaFormat` property of the message to specify its mime type',
       'application/vnd.custom.type;version=1.0.0',
       'application/vnd.custom.type+json;version=1.0.0',
     ]
   }
   

2. Before parsing an AsyncAPI document with a parser, register the additional custom schema parser:

   const myCustomParser = require('mycustomParser');
   
   parser.registerSchemaParser(myCustomParser);
   

Error types

This package throws a bunch of different error types. All errors contain a type (prefixed by this repo URL) and a title field. The following table describes all the errors and the extra fields they include:

Type	Extra Fields	Description
null-or-falsey-document	None	The AsyncAPI document is null or a JS "falsey" value.
invalid-document-type	None	The AsyncAPI document is not a string nor a JS object.
invalid-json	detail, location	The AsyncAPI document is not valid JSON.
invalid-yaml	detail, location	The AsyncAPI document is not valid YAML.
impossible-to-convert-to-json	detail	Internally, this parser only handles JSON so it tries to immediately convert the YAML to JSON. This error means this process failed.
missing-asyncapi-field	parsedJSON	The AsyncAPI document doesn't have the mandatory asyncapi field.
unsupported-version	detail, parsedJSON, validationErrors	The version of the asyncapi field is not supported. Typically, this means that you're using a version below 2.0.0.
dereference-error	parsedJSON, refs	This means the parser tried to resolve and dereference $ref's and the process failed. Typically, this means the $ref it's pointing to doesn't exist.
unexpected-error	parsedJSON	We have our code covered with try/catch blocks and you should never see this error. If you see it, please open an issue to let us know.
validation-errors	parsedJSON, validationErrors	The AsyncAPI document contains errors. See validationErrors for more information.
impossible-to-register-parser	None	Registration of custom message parser failed.

For more information about the ParserError class, check out the documentation.

Develop

1. Run tests with npm test
2. Write code and tests.
3. Make sure all tests pass npm test

Release regenerates API documentation and browser bundle, so you do not have to regenerate it manually with npm run docs and npm run prepublishOnly.

Contributing

Read CONTRIBUTING guide.