From 856ddb6c2386fda17cfd62080275179ab1c9dac2 Mon Sep 17 00:00:00 2001 From: Viacheslav Turovskyi Date: Tue, 4 Jul 2023 23:16:01 +0000 Subject: [PATCH] feat: support context file location in repository --- docs/context.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 69 insertions(+), 3 deletions(-) diff --git a/docs/context.md b/docs/context.md index fdf4359f576..99df78dc67f 100644 --- 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",