feat: support context file location in repository

asyncapi · Jul 4, 2023 · d51bc4e · d51bc4e
1 parent 6d89ea6
commit d51bc4e
Showing 1 changed file with 69 additions and 3 deletions.
diff --git a/docs/context.md b/docs/context.md
@@ -19,13 +19,13 @@ If your use case is that you work with multiple repositories, you might want to
 
 ### How to add context to a project
 
-##### Manually:
+#### Manually:
   - Create file `.asyncapi-cli` containing [minimal empty context file](#minimalEmptyContextFile) in:
     - current directory
     - root of current repository
     - user's home directory
 
-##### Using CLI's `init` command:
+#### Using CLI's `init` command:
 
 `asyncapi config context init [CONTEXT-FILE-PATH]`
 
@@ -40,6 +40,72 @@ 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](https://github.com/amadeus4dev-examples/amadeus-async-flight-status/tree/ff433b6d320a3a6a2499976cbf0782353bc57c16) of the [Amadeus Airline Platform](https://amadeus.com/en/industries/airlines/airline-platform), with multiple microservices and their AsyncAPI documents.
+
+```bash
+# One-time initialization of '.asyncapi-cli' file
+(main)$ asyncapi config context init
+Initialized context /amadeus-async-flight-status/.asyncapi-cli
+
+# Adding first context
+(main)$ asyncapi config context add subscriber subscriber/asyncapi.yaml
+Added context "subscriber".
+You can set it as your current context: asyncapi config context use subscriber
+You can use this context when needed by passing subscriber as a parameter: asyncapi validate subscriber
+
+# Adding more contexts
+(main)$ asyncapi config context add notifier notifier/asyncapi.yaml
+Added context "notifier".
+You can set it as your current context: asyncapi config context use notifier
+You can use this context when needed by passing notifier as a parameter: asyncapi validate notifier
+
+(main)$ asyncapi config context add monitor monitor/asyncapi.yaml
+Added context "monitor".
+You can set it as your current context: asyncapi config context use monitor
+You can use this context when needed by passing monitor as a parameter: asyncapi validate monitor
+
+# Setting monitor as default context
+(main)$ asyncapi config context use monitor
+monitor is set as current
+
+# Now you do not even have to remember the context name, and default 'monitor/asyncapi.yaml' will be validated
+(main)$ asyncapi validate
+File monitor/asyncapi.yaml is valid but has (itself and/or referenced documents) governance issues.
+monitor/asyncapi.yaml
+  1:1       warning  asyncapi-defaultContentType      AsyncAPI document should have "defaultContentType" field.
+  1:1       warning  asyncapi-id                      AsyncAPI document should have "id" field.
+  1:1       warning  asyncapi2-tags                   AsyncAPI object should have non-empty "tags" array.
+  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
+  2:6       warning  asyncapi-info-contact            Info object should have "contact" object.                                                     info
+ 19:15      warning  asyncapi2-operation-operationId  Operation should have an "operationId" field defined.                                         channels.flight/update.subscribe
+ 26:13      warning  asyncapi2-operation-operationId  Operation should have an "operationId" field defined.                                         channels.flight/queue.publish
+✖ 7 problems (0 errors, 6 warnings, 1 info, 0 hints)
+
+# You can now use context name when running AsyncAPI commands, no need to remember file location like 'notifier/asyncapi.yaml'
+(main)$ asyncapi validate notifier
+File notifier/asyncapi.yaml is valid but has (itself and/or referenced documents) governance issues.
+notifier/asyncapi.yaml
+  1:1       warning  asyncapi-defaultContentType      AsyncAPI document should have "defaultContentType" field.
+  1:1       warning  asyncapi-id                      AsyncAPI document should have "id" field.
+  1:1       warning  asyncapi2-tags                   AsyncAPI object should have non-empty "tags" array.
+  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
+  2:6       warning  asyncapi-info-contact            Info object should have "contact" object.                                                     info
+ 18:13      warning  asyncapi2-operation-operationId  Operation should have an "operationId" field defined.                                         channels.flight/update.publish
+✖ 6 problems (0 errors, 5 warnings, 1 info, 0 hints)
+
+# Switch default context 
+(main)$ asyncapi config context use notifier
+notifier is set as current
+
+# List all contexts
+(main)$ asyncapi config context list
+monitor: monitor/asyncapi.yaml
+notifier: notifier/asyncapi.yaml
+subscriber: subscriber/asyncapi.yaml
+```
+
 ### Context File structure
 
 ##### Fixed Fields
@@ -73,7 +139,7 @@ Stringified JSON:
 
 ##### Context File Example
 
-Example of a context file utilizing [Event Driven Flight status notification service](https://github.com/amadeus4dev-examples/amadeus-async-flight-status/tree/ff433b6d320a3a6a2499976cbf0782353bc57c16) of the Amadeus Airline Platform:
+Example of a context file for [Event Driven Flight status notification service](https://github.com/amadeus4dev-examples/amadeus-async-flight-status/tree/ff433b6d320a3a6a2499976cbf0782353bc57c16) of the [Amadeus Airline Platform](https://amadeus.com/en/industries/airlines/airline-platform), with multiple microservices and their AsyncAPI documents:
 ```
 {
   "current": "monitor",