Skip to content

cds import : updating doc for asyncapi import #111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
May 3, 2023
Merged

cds import : updating doc for asyncapi import #111

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ed0b207
updating for asyncapi import
muskansethi1 Apr 27, 2023
0130b68
revert change
muskansethi1 Apr 27, 2023
d690702
added table and some edits
renejeglinsky May 2, 2023
b5a3e79
Merge branch 'main' into asyncapi-import
renejeglinsky May 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions guides/using-services.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,16 +148,15 @@ By default, CAP works with OData V4 and the EDMX export is in this protocol vers
Import the API to your project using `cds import`.

```sh
cds import ~/Downloads/API_BUSINESS_PARTNER.edmx --keep-namespace --as cds
cds import <input_file> --as cds
```

| Option | Description |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--keep-namespace` | Keep the namespace of the existing service. Otherwise, the namespace is changed to the file's base name when converting the file to CSN.<br> **Note:** In this example, it would be still `API_BUSINESS_PARTNER`. |
Copy link
Contributor Author

@muskansethi1 muskansethi1 May 3, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where do you think that we should give a description of this option? @renejeglinsky

Copy link
Contributor

@renejeglinsky renejeglinsky May 3, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall I felt, that we do have here a lot of reference content that maybe should find a home somewhere else. I'm not sure yet where that home would be. Having said that, I think that it's sufficient to have options documented in CLI help. Everything else is nice to have if it makes sense. So here, we don't use --keep-namespace anymore that's why I don't see the need to explain it here.

| `--as cds` | The import creates a CDS file (for example _API_BUSINESS_PARTNER.cds_) instead of a CSN file. |


This adds the API in CSN format to the _srv/external_ folder and also copies the EDMX file into that folder. Additionally, for **Node.js** it adds the API as an external OData service to your _package.json_. You use this declaration later to connect to the remote service [using a destination](#use-destinations-with-node-js).
This adds the API in CDS format to the _srv/external_ folder and also copies the input file into that folder. Additionally, for **Node.js** it adds the API as an external service to your _package.json_. You use this declaration later to connect to the remote service [using a destination](#use-destinations-with-node-js).

```json
"cds": {
Expand Down Expand Up @@ -189,9 +188,17 @@ Now run `cds import <filename>`
- `--force` is applicable only in combination with `--as` option. By default the `--force` flag is set to false.
> If set to true, existing CSN/CDS files from previous imports are overwritten.

The kind `odata-v2` is set when importing EDMX definitions of OData V2 format. When importing OData V4, the kind `odata` is set, which is an alias for kind `odata-v4`.
When importing definitions, the `kind` is set according to the following mapping:

|Imported Format | Used `kind` |
|---------|---------|
| OData V2 | `odata-v2` |
| OData V4 | `odata` (alias for `odata-v4`) |
| OpenAPI | `rest` |
| AsyncAPI | `odata` |

[Learn more about type mappings from OData to CDS and vice versa.](../node.js/cds-dk#special-type-mappings){.learn-more}

::: tip
Always use OData V4 (`odata`) when calling another CAP service.
:::
Expand Down
16 changes: 15 additions & 1 deletion node.js/cds-dk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ const cds = require('@sap/cds-dk')

## <span style="color:#800; font-weight:500">cds</span>.import <i> (file, options) &#8594; [csn](../cds/csn) </i> { #import }

As an application developer, you have the option to convert OData specification (EDMX / XML), or OpenAPI specification (JSON) files to CSN from JavaScript API as an alternative to the `cds import` command.
As an application developer, you have the option to convert OData specification (EDMX / XML), OpenAPI specification (JSON) or AsyncAPI specification (JSON) files to CSN from JavaScript API as an alternative to the `cds import` command.

> `cds.import` is available in the CDS development tool kit *version 4.3.1* onwards .

Expand Down Expand Up @@ -90,6 +90,15 @@ const csn = await cds.import.from.openapi(OpenAPI_JSON_file)
```
<br>

## <span style="color:#800; font-weight:500">cds</span>.import.from.asyncapi <i> (file) &#8594; [csn](../cds/csn) </i> { #import-from-asyncapi }

This API can be used to convert the AsyncAPI specification file (JSON) into CSN.
The API signature looks like this:
```js
const csn = await cds.import.from.asyncapi(AsyncAPI_JSON_file)
```
<br>

Example:

```js
Expand All @@ -100,10 +109,14 @@ module.exports = async (srv) => {
cds.import('./odata_sample.edmx', { includeNamespaces: 'sap,c4c', keepNamespace: true }),
// for openapi
cds.import('./openapi_sample.json'),
// for asyncapi
cds.import('./asyncapi_sample.json'),
// for odata
cds.import.from.edmx('./odata_sample.xml', { includeNamespaces: '*', keepNamespace: false }),
// for openapi
cds.import.from.openapi('./openapi_sample.json')
// for asyncapi
cds.import.from.asyncapi('./asyncapi_sample.json')
]);

for (let i = 0; i < csns.length; i++) {
Expand All @@ -129,3 +142,4 @@ The following mapping is used during the import of an external service API, see
| _Edm.DateTime<br>Precision : Second_ <sup>1</sup> | `cds.DateTime` + `@odata.Type:'Edm.DateTime'` + `@odata.Precision:0` |

<sup>1</sup> only OData V2