The AsyncAPI Parser is a package used to parse and validate the AsyncAPI documents in your Node.js or browser application. These documents can be either in YAML or JSON format.
The Parser validates these documents using dedicated schema-supported plugins.
- AsyncAPI schema (no plugin needed)
- OpenAPI schema
- JSON schema
- Avro schema
- RAML data-type schema
If the document is valid, the Parser returns an
AsyncAPIDocument instance with a set of helper functions that enable easier access to the contents of the AsyncAPI document. The parser provides dereferenced output. During the dereference process, the AsyncAPI parser substitutes a reference with a full definition. The dereferenced output is always in JSON format. The parser provides a message listing all errors if a document is invalid. The original AsyncAPI document is part of the Template Context as the generator also passes the original AsyncAPI document to the template context.
The following AsyncAPI document example has two channels:
channelTwo. Each channel has one operation and a single message:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
asyncapi: '2.5.0' info: title: Demo API version: '1.0.0' channels: channelOne: publish: summary: This is the first sample channel operationId: onMessage message: name: FirstMessage payload: id: type: integer minimum: 0 description: Id of the channel sentAt: type: string format: date-time description: Date and time when the message was sent. channelTwo: publish: summary: This is the second sample channel operationId: messageRead message: name: SecondMessage payload: id: type: integer minimum: 0 description: Id of the channel sentAt: type: string format: date-time description: Date and time when the message was sent.
We can use helper functions provided by the Parser to operate on the above JSON file. For example, we can use the helper method
asyncAPIDocument.channelNames(), which returns an array of all channel names currently present in the AsyncAPI document. Another example where you can use a helper function is to list out messages present in your JSON file. Instead of fetching a single message one at a time, you can use the function
asyncAPIDocument.allMessages() that returns the map of all messages in your AsyncAPI document.
const channelNames = asyncAPIDocument.channelNames(); const messages = asyncAPIDocument.allMessages();
The Parser gives you access to a number of these helper functions that you can implement to access the contents of your AsyncAPI document.
AsyncAPI document validation process
- AsyncAPI document is fed as an input to the Generator.
- Generator sends the AsyncAPI document to the Parser as asyncapiString; the stringified version of the original AsyncAPI document.
- The Parser uses additional plugins such as the OpenAPI, RAML, or Avro schemas to validate custom schemas of message payloads defined in the AsyncAPI document.
invalid-document-typeerror. Similarly, you may encounter errors such as:
- If the document is valid, the Parser modifies the AsyncAPI document, returns a set of helper functions, and bundles them together into the asyncapi variable. These helper functions in the form of an asyncapi variable are passed to the Template Context.
- The Template Context passes all of these values to the Render Engine of your choice. Finally, the Render Engine generates whatever output you may have specified in your template. (i.e. code, documentation, diagrams, pdfs, applications, etc.)
To learn more about the Parser and access all of its features, check out the AsyncAPI Parser’s GitHub repository.