Publishing to AsyncAPI
You can convert events in CDS models to the AsyncAPI specification, a widely adopted standard used to describe and document message-driven asynchronous APIs.
CDS Type to AsyncAPI Mapping
CDS Type | AsyncAPI Supported Types |
---|---|
UUID |
{ “type”: “string”, “format”: “uuid” } |
Boolean |
{ “type”: “boolean” } |
Integer |
{ “type”: “integer” } |
Integer64 |
{ “type”: “string”, “format”: “int64” } |
Decimal , {precision, scale} |
{ “type”: “string”, “format”: “decimal”, “formatPrecision”: |
Decimal , without scale |
{ “type”: “string”, “format”: “decimal”, “formatPrecision”: |
Decimal , without precision and scale |
{ “type”: “string”, “format”: “decimal” } |
Double |
{ “type”: “number” } |
Date |
{ “type”: “string”, “format”: “date” } |
Time |
{ “type”: “string”, “format”: “partial-time” } |
DateTime |
{ “type”: “string”, “format”: “date-time” } |
Timestamp |
{ “type”: “string”, “format”: “date-time” } |
String |
{ “type”: “string”, “maxLength”: length } |
Binary |
{ “type”: “string”, “maxLength”: length } |
LargeBinary |
{ “type”: “string” } |
LargeString |
{ “type”: “string” } |
Usage from CLI
Use the following command, to convert all services in srv/
and store the generated AsyncAPI documents in the docs/
folder:
cds compile srv --service all -o docs --to asyncapi
For each service that is available in the srv/
files, an AsyncAPI document with the service name is generated in the output folder.
If you want to generate one AsyncAPI document for all the services, you can use --asyncapi:merged
flag:
cds compile srv --service all -o docs --to asyncapi --asyncapi:merged
Learn how to programmatically convert the CSN file into an AsyncAPI Document
Presets
Use presets to add configuration for the AsyncAPI export tooling.
cdsrc.json
{
"export": {
"asyncapi": {
"application_namespace": "sap.example"
.....
}
}
}
Term | Preset Target | AsyncAPI field | Remarks |
---|---|---|---|
merged.title |
Service | info.title | Mandatory when --asyncapi:merged flag is given. title from here is used in the generated AsyncAPI document. |
merged.version |
Service | info.version | Mandatory when --asyncapi:merged flag is given. version from here is used in the generated AsyncAPI document |
merged.description |
Service | info.description | Optional when --asyncapi:merged flag is given. description from here is used in the generated AsyncAPI document. |
merged.short_text |
Service | x-sap-shortText | Optional when --asyncapi:merged flag is given. The value from here is used in the generated AsyncAPI document. |
application_namespace |
Document | x-sap-application-namespace | Mandatory |
event_spec_version |
Event | x-sap-event-spec-version | |
event_source |
Event | x-sap-event-source | |
event_source_params |
Event | x-sap-event-source-parameters | |
event_characteristics |
Event | x-sap-event-characteristics |
Annotations
Use annotations to add configuration for the AsyncAPI export tooling.
Annotations will take precedence over presets.
Term (@AsyncAPI. ) |
Annotation Target |
AsyncAPI field | Remarks |
---|---|---|---|
Title |
Service | info.title | Mandatory |
SchemaVersion |
Service | info.version | Mandatory |
Description |
Service | info.description | |
StateInfo |
Service | x-sap-stateInfo | |
ShortText |
Service | x-sap-shortText | |
EventSpecVersion |
Event | x-sap-event-spec-version | |
EventSource |
Event | x-sap-event-source | |
EventSourceParams |
Event | x-sap-event-source-parameters | |
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. |
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'
event SampleEntity.Changed.v1 : projection on CatalogService.SampleEntity;
}