chore: move and extend AsyncAPI docs

get-started/feature-matrix.md

@@ -169,7 +169,7 @@ Following is an index of the features currently covered by CAP, with status and
 
 | Outbound Protocol Support                                        | CDS <sup>1</sup> | Node.js | Java |
 |------------------------------------------------------------------|:----------------:|:-------:|:----:|
-| [REST/OpenAPI](../tools/apis/cds-import#cdsimportfromopenapi) |       <X/>       |  <X/>   | <X/> |
+| [REST/OpenAPI](../tools/apis/cds-import#from-openapi)            |       <X/>       |  <X/>   | <X/> |
 | OData V2                                                         |       <X/>       |  <X/>   | <X/> |
 | OData V4                                                         |       <X/>       |  <X/>   | <X/> |
 | GraphQL<sup>2</sup>                                              |       <C/>       |  <C/>   | <C/> |

guides/protocols/asyncapi.md

@@ -10,11 +10,16 @@ description: >
   }
 </style>
 
-
 # Publishing to AsyncAPI
 
 You can convert events in CDS models to the [AsyncAPI specification](https://www.asyncapi.com), a widely adopted standard used to describe and document message-driven asynchronous APIs.
 
+Install the plugin like so:
+
+```sh
+npm add -D @cap-js/asyncapi
+```
+
 [[toc]]
 
 ## Usage from CLI { #cli}
@@ -32,7 +37,25 @@ If you want to generate one AsyncAPI document for all the services, you can use
 cds compile srv --service all -o docs --to asyncapi --asyncapi:merged
 ```
 
-[Learn how to programmatically convert the CSN file into an AsyncAPI Document](../../node.js/cds-compile#asyncapi){.learn-more}
+## Programmatic Usage { #programmatic}
+
+```js
+const cds = require('@sap/cds')
+const { compile } = require('@cap-js/asyncapi')
+
+const csn = await cds.load(cds.env.folders.srv)
+const doc = compile(csn)
+```
+
+## Importing AsyncAPI { #import}
+
+Use `cds import` to convert an AsyncAPI document into a CDS service definition:
+
+```sh
+cds import --asyncapi ~/Downloads/BookStore_AsyncAPI.json
+```
+
+[Learn more about `cds.import`](../../tools/apis/cds-import#from-asyncapi){.learn-more}
 
 ## Presets { #presets}
 
@@ -84,22 +107,21 @@ Annotations will take precedence over [presets](#presets).
 | `EventCharacteristics` | Event             | x-sap-event-characteristics   |                                                                                                                         |
 | `EventStateInfo`       | Event             | x-sap-stateInfo               |                                                                                                                         |
 | `EventSchemaVersion`   | Event             | x-sap-event-version           |                                                                                                                         |
-| `EventType`            | Event             |                               | Optional; The value from this annotation will be used to<br> overwrite the default event type in the AsyncAPI document. |
+| `EventType`            | Event             |                               | Optional; The value from this annotation will be used to overwrite the default event type in the AsyncAPI document. |
 
 For example:
 
 ```cds
 @AsyncAPI.Title        : 'CatalogService Events'
 @AsyncAPI.SchemaVersion: '1.0.0'
 @AsyncAPI.Description  : 'Events emitted by the CatalogService.'
-
 service CatalogService {
+
   @AsyncAPI.EventSpecVersion    : '2.0'
   @AsyncAPI.EventCharacteristics: {
     ![state-transfer]: 'full-after-image'
   }
-  @AsyncAPI.EventSchemaVersion       : '1.0.0'
-
+  @AsyncAPI.EventSchemaVersion  : '1.0.0'
   event SampleEntity.Changed.v1 : projection on CatalogService.SampleEntity;
 }
 ```
@@ -113,14 +135,14 @@ For example, if both `@AsyncAPI.ShortText` and `@AsyncAPI.Extensions: { ![sap-sh
 For example:
 
 ```cds
-@AsyncAPI.Extensions   : {
-  ![foo-bar]                    : 'baz',
-  ![sap-shortText]              : 'Service Base 1'
+@AsyncAPI.Extensions: {
+  ![foo-bar]: 'baz',
+  ![sap-shortText]: 'Service Base 1'
 }
-
 service CatalogService {
-  @AsyncAPI.Extensions          : {
-    ![sap-event-source]           : '/{region}/sap.app.test'
+
+  @AsyncAPI.Extensions: {
+    ![sap-event-source]: '/{region}/sap.app.test'
   }
   event SampleEntity.Changed.v1 : projection on CatalogService.SampleEntity;
 }

node.js/cds-compile.md

@@ -232,15 +232,6 @@ Reconstructs [CDL](../cds/cdl.md) source code for the given csn model.
 
 
 
-### .asyncapi() {.method}
-
-
-Convert the CSN file into an AsyncAPI document:
-
-```js
-const doc = cds.compile.to.asyncapi(csn_file)
-```
-
 
 
 

tools/apis/cds-import.md

@@ -47,7 +47,7 @@ It accepts a list of namespaces whose attributes are to be retained in the CSN /
 
 <br>
 
-## cds.import.from.edmx() {.method}
+## cds.import.from.edmx() {.method #from-edmx}
 
 This API can be used to convert the OData specification file (EDMX / XML) into CSN.
 The API signature looks like this:
@@ -58,7 +58,7 @@ const csn = await cds.import.from.edmx(ODATA_EDMX_file, options)
 
 <br>
 
-## cds.import.from.openapi() {.method}
+## cds.import.from.openapi() {.method #from-openapi}
 
 This API can be used to convert the OpenAPI specification file (JSON) into CSN.
 The API signature looks like this:
@@ -69,7 +69,7 @@ const csn = await cds.import.from.openapi(OpenAPI_JSON_file)
 
 [Learn more about OpenAPI to OData Mapping.](#openapi-to-cds-odata-csn-conversion-mapping){.learn-more}
 
-## cds.import.from.asyncapi() {.method}
+## cds.import.from.asyncapi() {.method #from-asyncapi}
 
 This API can be used to convert the AsyncAPI specification file (JSON) into CSN.
 The API signature looks like this: