6 AsyncAPI Validation Tools

6 AsyncAPI Validation Tools

Posted in

AsyncAPI specification is a widely used open-source standard for defining and documenting application programming interfaces (APIs) in an asynchronous environment. The specification lays the foundation for a greater and better tooling ecosystem for event-driven architecture. But as its popularity grows, developers are increasingly looking for tools to help them validate the accuracy of their AsyncAPI documents.

These AsyncAPI validation tools are designed to check for errors and inconsistencies in AsyncAPI documents, making it easier for developers to create well-structured APIs. Several popular AsyncAPI validation tools are available to help ensure the accuracy and integrity of your AsyncAPI specification.

In this blog post, we’ll discuss some of the most widely used AsyncAPI validation tools available. We’ll see how they can help developers ensure the accuracy of their AsyncAPI documents.

1. AML Modeling Framework (AMF)

The AML Modeling Framework (AMF) is an open-source library that serves as a powerful tool for working with AsyncAPI and other API specifications. AMF is capable of parsing, transforming, validating, and rendering arbitrary models, making it an invaluable asset for developers working with AsyncAPI.

One of the key components of AMF is the API Contract Model, which contains all the information expressed in the source API document. This model can be used for validations, transformations, and conversions, making it highly versatile and adaptable to different use cases.
What sets AMF apart is its support for custom models and parsers, which can be defined using the AML (API Modeling Language) language. This allows developers to create their own models and parsers tailored to their specific needs and requirements.

To illustrate the power of AMF, let’s consider an example where an OpenAPI Specification (OAS) 3.0 API document needs to be parsed, validated, transformed, and rendered in RAML 1.0. With AMF, this can be achieved seamlessly, simplifying the process and saving valuable development time.

If you want to learn more about the AML Modeling Framework and its capabilities, various resources are available, including the official documentation, tutorials, and code examples. These resources can provide a deeper understanding of AMF and help you unlock its full potential for working with AsyncAPI and other API specifications.

2. Spectral

Spectral is a powerful and extensible linting tool specifically designed for API specifications. It helps developers ensure the quality, consistency, and adherence to best practices of their AsyncAPI and OpenAPI specifications.

Spectral operates based on three key concepts: rules, rulesets, and functions. Rules define what to look for in the API specification, rulesets group related rules together, and functions perform specific operations on the API document.

Spectral comes bundled with core functions and rulesets for OpenAPI v2 and v3 and AsyncAPI v2, making it easy to get started. It supports YAML and JSON file formats, providing flexibility for different project requirements.

One of the most popular use cases of Spectral is automating the enforcement of API style guides. Traditionally, companies would write these style guides as wiki pages, and many examples are available on API Stylebook. However, many of these rules can be automated using Spectral.

To make the most out of Spectral, it’s essential to learn more about how rulesets work. By understanding and customizing the rulesets, developers can tailor Spectral to their specific needs and ensure their API specifications are always up to standard.

3. AsyncAPI Parser

The AsyncAPI Parser is a powerful tool that validates AsyncAPI documents according to dedicated schemas. It supports documents in both YALM and JSON formats. If a document is invalid, the parser provides a detailed message listing all errors encountered. On the other hand, if a document is valid, the parser provides a dereferenced output, which is always in the JSON format.

To install the AsyncAPI Parser package, you can use the command npm install -g @asyncapi/parser. You can use the AsyncAPI Parser either in the terminal or with Golang.

Here are two examples of how you can use the AsyncAPI Parser in the terminal:

  1. To validate an AsyncAPI document: asyncapi validate <path-to-asyncapi-doc>
  2. To dereference an AsyncAPI document: asyncapi dereference <path-to-asyncapi-doc> --output <output-file>

4. AsyncAPI Parser Wrapper

The AsyncAPI Parser wrapper is a Java library that enables parsing and validation of AsyncAPI documents in Java applications. It acts as a Java wrapper over a JavaScript Parser implemented using J2V8. To install the parser, you can clone the repository and build the library using the provided build script. Alternatively, you can add the dependency to your Maven or Gradle project by specifying the group, artifact, and version in your project’s configuration file. This library is a powerful tool for Java developers who want to incorporate AsyncAPI validation into their applications.

5. Asyncapi-Validator

Another popular tool for validating AsyncAPI schemas is the asyncapi-validator package. This package supports AsyncAPI Schema version 2.0.0 and above. It provides a simple and straightforward way to validate AsyncAPI schemas and check for any errors or inconsistencies.

One of the notable features of the asyncapi-validator is the .validateByMessageId() method. This method allows you to validate a specific message based on its messageId. It requires an AsyncAPI Schema version of at least v2.4.0. This feature is handy when you want to validate a specific message within your schema.

Another important aspect of the asyncapi-validator is the .schema property. This property allows you to access the AsyncAPI schema in JSON format. You can use this property to perform additional checks or validations outside of the built-in validation methods provided by the package.

By using the asyncapi-validator, you can ensure that your AsyncAPI schemas comply with the defined standards and avoid any potential issues in your messaging system. This tool can significantly improve the quality and reliability of your AsyncAPI specifications.

6. AsyncAPI GitHub Action

The AsyncAPI GitHub Action is a valuable tool that allows you to easily validate your AsyncAPI schema file directly within your GitHub repository. This action is designed to check whether the AsyncAPI schema file is valid or not, ensuring that it adheres to the AsyncAPI specification.

To use this action, you simply need to provide the file path of your AsyncAPI schema file, starting from the root of your GitHub repository. This enables the action to locate and validate the file seamlessly.

In addition, the AsyncAPI GitHub Action allows you to specify the version of the action you want to use by appending the @v<release-version> to the action’s name. The latest release version can be found on the releases page of the GitHub repository.

By leveraging the power of the AsyncAPI GitHub Action, you can automate the validation process for your AsyncAPI schema file, ensuring its accuracy and compliance. This action saves time and effort as it seamlessly integrates into your existing GitHub workflow.

How to Validate your AsyncAPI Definitions

Developers can also validate their AsyncAPI definitions using the validation tool provided by AsyncAPI itself. This tool is available as a command line interface (CLI), making it easily accessible for developers.

The CLI can be used to validate both YAML and JSON documents. To use the validation tool, developers must run a command with the path to their AsyncAPI document(s) as an argument. The tool supports validating a single document or an entire directory of documents. This flexibility allows developers to efficiently validate their AsyncAPI definitions, even in projects with multiple files.

The AsyncAPI validation tool performs a variety of checks to ensure the correctness and integrity of the definitions. It checks for syntax errors, missing fields, and other issues that could prevent a document from being successfully parsed. By detecting these errors early on, developers can avoid potential problems and save time in the long run.

Additionally, the validation tool also checks for semantic errors, such as incorrect field types or invalid values. This helps ensure that the AsyncAPI definitions adhere to the specifications and accurately represent the intended functionality.

The validation tool is open source and can be found on GitHub, providing developers with the opportunity to contribute, report issues, or suggest improvements. Furthermore, for developers who prefer working in a containerized environment, the validation tool is also available as a Docker image, making it even more convenient to use.

By utilizing the validation tool provided by AsyncAPI, developers can validate their AsyncAPI definitions quickly and effectively, ensuring the quality and accuracy of their messaging infrastructure.

Comparing The AsyncAPI Validation Tools

In summary, AsyncAPI validation tools are a set of powerful tools and libraries designed to help developers validate their AsyncAPI definitions and ensure that they conform to the AsyncAPI specification. These tools offer various features and functionalities, such as syntax validation, linting, and code generation, to help developers improve the quality and accuracy of their AsyncAPI documents. Here’s a review of how they all compare.

The AML Modeling Framework (AMF) provides a set of Java libraries that allow developers to parse, manipulate, and validate AsyncAPI documents. AMF leverages the power of JSON-LD to create a flexible and extensible modeling framework.

Spectral is another important tool for validating API definitions. It is a customizable JSON/YAML linter that allows developers to define and enforce custom validation rules on their AsyncAPI documents. Spectral provides a rich set of pre-built rules that cover common validation scenarios, making it easier for developers to ensure the quality of their AsyncAPI definitions.

AsyncAPI Parser and AsyncAPI Parser Wrapper are two libraries that provide developers with the ability to parse and manipulate AsyncAPI documents programmatically. These libraries allow developers to work with AsyncAPI documents in their preferred programming language, making it easier to integrate the validation process into their existing workflows.

The asyncapi-validator is a command-line tool that allows developers to validate AsyncAPI documents against the AsyncAPI specification. It provides a simple and intuitive interface, making it easy for developers to validate their AsyncAPI definitions.

Lastly, the AsyncAPI GitHub Action is a powerful automation tool that enables developers to integrate AsyncAPI validation into their CI/CD pipelines. This action allows developers to automatically validate their AsyncAPI definitions whenever changes are made, ensuring that only valid and compliant documents are deployed.

Overall, AsyncAPI Validation Tools provide developers with the necessary tools and libraries to validate and ensure the quality of their AsyncAPI definitions. By utilizing these tools, developers can reduce errors and inconsistencies in their AsyncAPI documents, leading to more reliable and efficient messaging systems.