Validate AsyncAPI document with Studio

Introduction

In this tutorial, you'll learn how to validate AsyncAPI documents using the AsyncAPI Studio tool.

You will start with a broken AsyncAPI document and troubleshoot via console errors step-by-step until you end up with a valid AsyncAPI document. This process will illustrate identifying REQUIRED properties in AsyncAPI documents.

Background context

An AsyncAPI document is a file that defines and annotates the different components of a specific Event-Driven API. The format of the file must be JSON or YAML. You can use this document to generate both documentation and code.

The AsyncAPI Studio tool allows you to develop an AsyncAPI document, validate it, preview it, convert it to the latest version, and visualize event flows.

Now let's experiment with an invalid file to see how errors are displayed and how to make that file valid again.

Copy invalid AsyncAPI document

Let's pretend you have an invalid AsyncAPI document.

1. Open Studio.

2. Copy and paste the below invalid AsyncAPI document:

1asyncapi: 3.0.0
2info:
3  title: Streetlights API
4  version: '1.0.0'
5  description: |
6    The Smartylighting Streetlights API allows you
7    to remotely manage the city lights.
8  license:
9    name: Apache 2.0
10    url: 'https://www.apache.org/licenses/LICENSE-2.0'
11
12servers:
13  mosquitto:
14    url: test.mosquitto.org
15    protocol: mqtt
16
17channels:
18  lightMeasured:
19    address: 'light/measured'
20    messages:
21      lightMeasuredMessage:
22        name: LightMeasured
23        payload:
24          type: object
25          properties:
26            id:
27              type: integer
28              minimum: true
29              description: Id of the streetlight.
30            lumens:
31              type: integer
32              minimum: 0
33              description: Light intensity measured in lumens.
34            sentAt:
35              type: string
36              format: date-time
37              description: Date and time when the message was sent.
38
39operations:
40  onLightMeasured:
41    action: 'receive'
42    summary: Inform about environmental lighting conditions for a particular streetlight.
43    channel:
44      $ref: '#/channels/lightMeasured'

Troubleshoot Studio errors

Let's fix the errors one by one until you end up with a valid AsyncAPI document.

1. You can see the error message on the screen: Empty or invalid document. Please fix errors/define AsyncAPI document.

2. Open DIAGNOSTICS, you can see more information related to your errors.

3. Fix the incorrect server information. Use host instead of url

1servers:
2  mosquitto:
3    host: test.mosquitto.org
4    protocol: mqtt

4. Read the next error: "minimum" property type must be number. Fix the minimum by changing it to: 0.

1          properties:
2            id:
3              type: integer
4              minimum: 0

5. Congratulations! You identified and fixed all the errors, and now have a valid AsyncAPI document.

Summary

In this tutorial, you learned how to validate an AsyncAPI document using the AsyncAPI Studio tool. You also learned to troubleshoot an invalid AsyncAPI document by following the error message directions in diagnostics. In doing so, you learned how to identify REQUIRED properties in all AsyncAPI documents.

Next steps

Now that you have completed this tutorial, go ahead to learn generate AsyncAPI messages (events) which you will be sending to your application.

You may also enjoy reading our AsyncAPI document validation guide.