From 5282edf85d8f90dd4c8adc66c8b35765db1c2d8a Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Thu, 13 Aug 2026 21:29:39 +0200 Subject: [PATCH 1/6] chore: extend `@cap-js/asyncapi` documentation --- guides/protocols/asyncapi.md | 36 ++++++++++++++++++++++++------------ node.js/cds-compile.md | 9 --------- 2 files changed, 24 insertions(+), 21 deletions(-) diff --git a/guides/protocols/asyncapi.md b/guides/protocols/asyncapi.md index 0566969d0b..a2f48c321c 100644 --- a/guides/protocols/asyncapi.md +++ b/guides/protocols/asyncapi.md @@ -10,11 +10,16 @@ description: > } - # 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,15 @@ 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) +``` ## Presets { #presets} @@ -84,7 +97,7 @@ 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
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: @@ -92,14 +105,13 @@ For example: @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 +125,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; } diff --git a/node.js/cds-compile.md b/node.js/cds-compile.md index 7c2ae8f405..e8bf44b44a 100644 --- a/node.js/cds-compile.md +++ b/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) -``` - From bff8cb4cb971ceb024ea6f38b992c5c3068375dd Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Thu, 13 Aug 2026 21:33:38 +0200 Subject: [PATCH 2/6] Update asyncapi.md --- guides/protocols/asyncapi.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/guides/protocols/asyncapi.md b/guides/protocols/asyncapi.md index a2f48c321c..994f911c9e 100644 --- a/guides/protocols/asyncapi.md +++ b/guides/protocols/asyncapi.md @@ -37,6 +37,16 @@ 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 ``` +## 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#cds-import-from-asyncapi){.learn-more} + ## Programmatic Usage { #programmatic} ```js From 037dd375ca80a0d8f301e41d94847e3ad4f19c3b Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Thu, 13 Aug 2026 21:42:16 +0200 Subject: [PATCH 3/6] better links --- guides/protocols/asyncapi.md | 2 +- tools/apis/cds-import.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/guides/protocols/asyncapi.md b/guides/protocols/asyncapi.md index 994f911c9e..1eba4b6f90 100644 --- a/guides/protocols/asyncapi.md +++ b/guides/protocols/asyncapi.md @@ -45,7 +45,7 @@ Use `cds import` to convert an AsyncAPI document into a CDS service definition: cds import --asyncapi ~/Downloads/BookStore_AsyncAPI.json ``` -[Learn more about `cds.import`](../../tools/apis/cds-import#cds-import-from-asyncapi){.learn-more} +[Learn more about `cds.import`](../../tools/apis/cds-import#from-asyncapi){.learn-more} ## Programmatic Usage { #programmatic} diff --git a/tools/apis/cds-import.md b/tools/apis/cds-import.md index b2bfb13854..607f27811f 100644 --- a/tools/apis/cds-import.md +++ b/tools/apis/cds-import.md @@ -47,7 +47,7 @@ It accepts a list of namespaces whose attributes are to be retained in the CSN /
-## 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)
-## 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: From 23516709458da4262c9f566a6def2e6fb4db757e Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Thu, 13 Aug 2026 21:44:06 +0200 Subject: [PATCH 4/6] Update asyncapi.md --- guides/protocols/asyncapi.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/guides/protocols/asyncapi.md b/guides/protocols/asyncapi.md index 1eba4b6f90..48e90fec36 100644 --- a/guides/protocols/asyncapi.md +++ b/guides/protocols/asyncapi.md @@ -37,16 +37,6 @@ 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 ``` -## 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} - ## Programmatic Usage { #programmatic} ```js @@ -57,6 +47,16 @@ 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} Use presets to add configuration for the AsyncAPI export tooling. From 27f36559dbeb073b0d0160ff187caec1cf77be67 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Thu, 13 Aug 2026 22:05:26 +0200 Subject: [PATCH 5/6] Update feature-matrix.md --- get-started/feature-matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/feature-matrix.md b/get-started/feature-matrix.md index d5751c8490..9420bc6c48 100644 --- a/get-started/feature-matrix.md +++ b/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 1 | Node.js | Java | |------------------------------------------------------------------|:----------------:|:-------:|:----:| -| [REST/OpenAPI](../tools/apis/cds-import#cdsimportfromopenapi) | | | | +| [REST/OpenAPI](../tools/apis/cds-import#from-openapi) | | | | | OData V2 | | | | | OData V4 | | | | | GraphQL2 | | | | From 0479de9e3aad1a009c749f82959f6b5da18118a3 Mon Sep 17 00:00:00 2001 From: Steffen Waldmann Date: Thu, 13 Aug 2026 22:06:06 +0200 Subject: [PATCH 6/6] Update feature-matrix.md --- get-started/feature-matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/get-started/feature-matrix.md b/get-started/feature-matrix.md index 9420bc6c48..9f1c8f2bda 100644 --- a/get-started/feature-matrix.md +++ b/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 1 | Node.js | Java | |------------------------------------------------------------------|:----------------:|:-------:|:----:| -| [REST/OpenAPI](../tools/apis/cds-import#from-openapi) | | | | +| [REST/OpenAPI](../tools/apis/cds-import#from-openapi) | | | | | OData V2 | | | | | OData V4 | | | | | GraphQL2 | | | |