Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/main' into review-java-documenta…
Browse files Browse the repository at this point in the history 
…tion
  • Loading branch information
@chgeo
chgeo committed Feb 23, 2024
2 parents 34e0efd + 7aef81b commit ace7fe4
Show file tree
Hide file tree
Showing 10 changed files with 623 additions and 0 deletions.
11 changes: 11 additions & 0 deletions .devcontainer/devcontainer.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{
"image":"mcr.microsoft.com/devcontainers/universal:2",
"customizations": {
"vscode": {
"extensions": [
"fcrespo82.markdown-table-formatter",
"vue.volar"
]
}
}
}
7 changes: 7 additions & 0 deletions .vscode/extensions.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
// List of extensions which should be recommended for users of this workspace.
"recommendations": [
"fcrespo82.markdown-table-formatter",
"vue.volar"
]
}
Binary file added advanced/publishing-apis/assets/openapi-diagram.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added advanced/publishing-apis/assets/swagger-link.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
134 changes: 134 additions & 0 deletions advanced/publishing-apis/asyncapi.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
---
shorty: AsyncAPI
synopsis: >
About how to convert events in CDS models to AsyncAPI documentation.
redirect_from: advanced/asyncapi
status: released
---

<style scoped>
/* expand this extra wide table on big screens */
@media screen and (min-width: 1600px) {
table {
min-width: fit-content;
width: max-content;
position: relative; z-index: 10; /* make the wide table flow over the aside section on the right */
}
}
</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.


## Usage from CLI { #cli}

Use the following command to convert all services in `srv/` and store the generated AsyncAPI documents in the `docs/` folder:

```sh
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:

```sh
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#to-asyncapi){.learn-more}

## Presets { #presets}

Use presets to add configuration for the AsyncAPI export tooling.

::: code-group
```json [.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.<br> `title` from here is used in the generated AsyncAPI document. |
| `merged.version` | Service | info.version | Mandatory when `--asyncapi:merged` flag is given.<br> `version` from here is used in the generated AsyncAPI document |
| `merged.description` | Service | info.description | Optional when `--asyncapi:merged` flag is given.<br> `description` from here is used in the generated AsyncAPI document. |
| `merged.short_text` | Service | x-sap-shortText | Optional when `--asyncapi:merged` flag is given.<br> 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 { #annotations}

Use annotations to add configuration for the AsyncAPI export tooling.

::: tip
Annotations will take precedence over [presets](#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<br> 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'
event SampleEntity.Changed.v1 : projection on CatalogService.SampleEntity;
}
```

## Type Mapping { #mapping}

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": <precision>, "formatScale": <scale> }` |
| `Decimal`, without scale | `{ "type": "string", "format": "decimal", "formatPrecision": <precision> }` |
| `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" }` |
10 changes: 10 additions & 0 deletions advanced/publishing-apis/index.data.ts
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import { basename } from 'node:path'
import { createContentLoader } from 'vitepress'
import filter from '../../.vitepress/theme/components/indexFilter.ts'

const basePath = basename(__dirname)
export default createContentLoader([`**/${basePath}/*.md`], {
transform(rawData) {
return filter(rawData, `/${basePath}/`)
}
})
16 changes: 16 additions & 0 deletions advanced/publishing-apis/index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
---
status: released
synopsis: How to publish APIs in different formats
---

# Publishing APIs

{{ $frontmatter.synopsis }}


<script setup>
import { data as pages } from './index.data.ts'
</script>

<br>
<IndexList :pages='pages' />
Loading

0 comments on commit ace7fe4

Please sign in to comment.