Context concept

Overview

AsyncAPI CLI provides functionality called context. It's purpose is to help to work with AsyncAPI CLI in large projects where you do not have just one service exposing AsyncAPI document, but multiple.

Event driven architecture involves multiple actors, subscribers and publishers. One time you want to validate document A and the other time you want to generate models from document B. Every time you do it, you need to provide to AsyncAPI CLI the location of the AsyncAPI document, which might be time consuming. You can workaround it with aliases in bash profiles or with other solutions but it is better to use context feature, as you can then store it in your repository and share with other team members.

In short it means that for example instead of writing asyncapi validate /some/folder/my-asyncapi.yml you can create a context called myasync that will be an alias for and point to /some/folder/my-asyncapi.yml. This way next time you use the CLI you can do asyncapi validate myasync.

Context File location

You can have a global context for your workstation, and a project specific context.

If your use case is that you work with multiple repositories, you might want to use a global context. The .asyncapi-cli context file is then located in your home directory. You can also store your custom .asyncapi-cli file in your project with custom configuration. This way when you run asyncapi config context add inside your project, the new context is added to the context file under your project.

How to add context to a project

Manually

Create file .asyncapi-cli containing minimal empty context file in:
- current directory
- root of current repository
- user's home directory

Using CLI's `init` command

asyncapi config context init [CONTEXT-FILE-PATH]

Where [CONTEXT-FILE-PATH] instructs CLI what directory should the file .asyncapi-cli containing minimal empty context file be created in:

current directory: asyncapi config context init . (default)
root of current repository: asyncapi config context init ./
user's home directory: asyncapi config context init ~

(if [CONTEXT-FILE-PATH] is omitted, empty context file is created in current directory)

Make use of newly created .asyncapi-cli by executing command:

asyncapi config context add [CONTEXT-NAME] [SPEC-FILE-PATH]

Setup example in a real project

Below you can see an example of context setup for Event Driven Flight status notification service of the Amadeus Airline Platform, with multiple microservices and their AsyncAPI documents.

1# One-time initialization of '.asyncapi-cli' file
2(main)$ asyncapi config context init
3Initialized context /amadeus-async-flight-status/.asyncapi-cli
4
5# Adding first context
6(main)$ asyncapi config context add subscriber subscriber/asyncapi.yaml
7Added context "subscriber".
8You can set it as your current context: asyncapi config context use subscriber
9You can use this context when needed by passing subscriber as a parameter: asyncapi validate subscriber
10
11# Adding more contexts
12(main)$ asyncapi config context add notifier notifier/asyncapi.yaml
13Added context "notifier".
14You can set it as your current context: asyncapi config context use notifier
15You can use this context when needed by passing notifier as a parameter: asyncapi validate notifier
16
17(main)$ asyncapi config context add monitor monitor/asyncapi.yaml
18Added context "monitor".
19You can set it as your current context: asyncapi config context use monitor
20You can use this context when needed by passing monitor as a parameter: asyncapi validate monitor
21
22# Setting monitor as default context
23(main)$ asyncapi config context use monitor
24monitor is set as current
25
26# Now you do not even have to remember the context name, and default 'monitor/asyncapi.yaml' will be validated
27(main)$ asyncapi validate
28File monitor/asyncapi.yaml is valid but has (itself and/or referenced documents) governance issues.
29monitor/asyncapi.yaml
30  1:1       warning  asyncapi-defaultContentType      AsyncAPI document should have "defaultContentType" field.
31  1:1       warning  asyncapi-id                      AsyncAPI document should have "id" field.
32  1:1       warning  asyncapi2-tags                   AsyncAPI object should have non-empty "tags" array.
33  1:11  information  asyncapi-latest-version          The latest version of AsyncAPi is not used. It is recommended update to the "2.6.0" version.  asyncapi
34  2:6       warning  asyncapi-info-contact            Info object should have "contact" object.                                                     info
35 19:15      warning  asyncapi2-operation-operationId  Operation should have an "operationId" field defined.                                         channels.flight/update.subscribe
36 26:13      warning  asyncapi2-operation-operationId  Operation should have an "operationId" field defined.                                         channels.flight/queue.publish
37✖ 7 problems (0 errors, 6 warnings, 1 info, 0 hints)
38
39# You can now use context name when running AsyncAPI commands, no need to remember file location like 'notifier/asyncapi.yaml'
40(main)$ asyncapi validate notifier
41File notifier/asyncapi.yaml is valid but has (itself and/or referenced documents) governance issues.
42notifier/asyncapi.yaml
43  1:1       warning  asyncapi-defaultContentType      AsyncAPI document should have "defaultContentType" field.
44  1:1       warning  asyncapi-id                      AsyncAPI document should have "id" field.
45  1:1       warning  asyncapi2-tags                   AsyncAPI object should have non-empty "tags" array.
46  1:11  information  asyncapi-latest-version          The latest version of AsyncAPi is not used. It is recommended update to the "2.6.0" version.  asyncapi
47  2:6       warning  asyncapi-info-contact            Info object should have "contact" object.                                                     info
48 18:13      warning  asyncapi2-operation-operationId  Operation should have an "operationId" field defined.                                         channels.flight/update.publish
49✖ 6 problems (0 errors, 5 warnings, 1 info, 0 hints)
50
51# Switch default context 
52(main)$ asyncapi config context use notifier
53notifier is set as current
54
55# List all contexts
56(main)$ asyncapi config context list
57monitor: monitor/asyncapi.yaml
58notifier: notifier/asyncapi.yaml
59subscriber: subscriber/asyncapi.yaml

Context File structure

Fixed Fields

Field Name	Type	Description
current	`string`	An optional string value representing one of context names, which is used as default in CLI. Default means you can run CLI commands without providing context name, like `asyncapi validate`, and it will run against the default - `current` - context.
store	Store Object	REQUIRED. Map of filesystem paths to target AsyncAPI documents.

Store Object

Map of filesystem paths to target AsyncAPI documents.

Patterned Fields

Field Pattern	Type	Description
{contextName}	`string`	An optional string value representing filesystem path to the target AsyncAPI document.

Minimal Empty Context File

Raw JSON:

1{
2  "store": {}
3}

Stringified JSON:

{"store":{}}

Context File Example

Example of a context file for Event Driven Flight status notification service of the Amadeus Airline Platform, with multiple microservices and their AsyncAPI documents:

1{
2  "current": "monitor",
3  "store": {
4    "monitor": "monitor/asyncapi.yaml",
5    "notifier": "notifier/asyncapi.yaml",
6    "subscriber": "subscriber/asyncapi.yaml"
7  }
8}

All commands for managing contexts are available under asyncapi config context CLI commands group.

On this page