Feature/add generateion of async api spec (#198)

* Add open api improvement

* Add new condition for open api generation

* Update generate-open-api.component.ts

* Add e2e tests

* Update generate-open-api.cy.ts

* Add error message when resource path clash with properteis

* Add documentation link to open api generation with resource path

* Add dialog for async api generation

* Update generate-async-api.component.ts

* Revert open api generation

* Update generate-open-api.component.ts

* Update generate-open-api.component.ts

* Fix cypress tests

* Add doc for async api

* Add async api doc into navigation

Author: michelu89

core/apps/ame-e2e/src/integration/generation/generation-async-api.cy.ts

@@ -0,0 +1,62 @@
+/* eslint-disable cypress/no-unnecessary-waiting */
+/*
+ * Copyright (c) 2024 Robert Bosch Manufacturing Solutions GmbH
+ *
+ * See the AUTHORS file(s) distributed with this work for
+ * additional information regarding authorship.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+/// <reference types="Cypress" />
+
+import {
+  GENERATION_tbApplicationIdInput,
+  GENERATION_tbChannelAddressInput,
+  GENERATION_tbGenerateAsyncApiButton,
+  GENERATION_tbOutputButton,
+  GENERATION_tbOutputButton_JSON,
+  GENERATION_writeSeparateFilesCheckbox,
+} from '../../support/constants';
+
+describe('Test generation and download of async api specification', () => {
+  it('Can generate valid JSON Async Api Specification', () => {
+    cy.visitDefault();
+    cy.startModelling()
+      .then(() => cy.openGenerationAsyncApiSpec().wait(500))
+      .then(() => cy.get(GENERATION_tbOutputButton).click())
+      .then(() => cy.get(GENERATION_tbOutputButton_JSON).click())
+      .then(() => cy.get(GENERATION_tbApplicationIdInput).focus().clear().type('application:id').blur())
+      .then(() => cy.get(GENERATION_tbChannelAddressInput).focus().clear().type('foo/bar').blur())
+      .then(() => cy.get(GENERATION_tbGenerateAsyncApiButton).click().wait(5000))
+      .then(() => cy.fixture('cypress/downloads/en-async-api.json'));
+  });
+
+  it('Can generate valid YAML Async Api Specification', () => {
+    cy.visitDefault();
+    cy.startModelling()
+      .then(() => cy.openGenerationAsyncApiSpec().wait(500))
+      .wait(500)
+      .then(() => cy.get(GENERATION_tbApplicationIdInput).focus().clear().type('application:id').blur())
+      .then(() => cy.get(GENERATION_tbChannelAddressInput).focus().clear().type('foo/bar').blur())
+      .then(() => cy.get(GENERATION_tbGenerateAsyncApiButton).click().wait(5000))
+      .then(() => cy.fixture('cypress/downloads/en-async-api.yaml'));
+  });
+
+  it('Can generate and download valid package for Async Api Specification', () => {
+    cy.visitDefault();
+    cy.startModelling()
+      .then(() => cy.openGenerationAsyncApiSpec().wait(500))
+      .then(() => cy.get(GENERATION_tbOutputButton).click())
+      .then(() => cy.get(GENERATION_tbOutputButton_JSON).click())
+      .then(() => cy.get(GENERATION_tbApplicationIdInput).focus().clear().type('application:id').blur())
+      .then(() => cy.get(GENERATION_tbChannelAddressInput).focus().clear().type('foo/bar').blur())
+      .then(() => cy.get(GENERATION_writeSeparateFilesCheckbox).click())
+      .then(() => cy.get(GENERATION_tbGenerateAsyncApiButton).click().wait(5000))
+      .then(() => cy.fixture('cypress/downloads/en-async-api.zip'));
+  });
+});

core/apps/ame-e2e/src/support/commands.ts

@@ -62,6 +62,12 @@ declare global {
        */
       openGenerationOpenApiSpec(): Chainable;
 
+      /**
+       * Custom command to open the generation of AsyncAPI specification.
+       * @returns {Cypress.Chainable} A chainable Cypress object.
+       */
+      openGenerationAsyncApiSpec(): Chainable;
+
       /**
        * Custom command to open the generation of documentation.
        * @returns {Cypress.Chainable} A chainable Cypress object.
@@ -529,25 +535,25 @@ Cypress.Commands.add('saveAspectModelToWorkspace', () => {
 Cypress.Commands.add('openGenerationOpenApiSpec', () => {
   cy.intercept(
     'POST',
-    'http://localhost:9091/ame/api/generate/open-api-spec?language=en&output=json&baseUrl=https://example.com&includeQueryApi=false&pagingOption=NO_PAGING&resourcePath=null&ymlProperties=&jsonProperties=',
+    'http://localhost:9091/ame/api/generate/open-api-spec?language=en&output=json&baseUrl=https://example.com&includeQueryApi=false&useSemanticVersion=false&pagingOption=NO_PAGING&resourcePath=null&ymlProperties=&jsonProperties=',
     {fixture: 'valid-open-api.json'},
   );
 
   cy.intercept(
     'POST',
-    'http://localhost:9091/ame/api/generate/open-api-spec?language=en&output=yaml&baseUrl=https://example.com&includeQueryApi=false&pagingOption=NO_PAGING&resourcePath=null&ymlProperties=&jsonProperties=',
+    'http://localhost:9091/ame/api/generate/open-api-spec?language=en&output=yaml&baseUrl=https://example.com&includeQueryApi=false&useSemanticVersion=false&pagingOption=NO_PAGING&resourcePath=null&ymlProperties=&jsonProperties=',
     {fixture: 'valid-open-api.yaml'},
   );
 
   cy.intercept(
     'POST',
-    'http://localhost:9091/ame/api/generate/open-api-spec?language=en&output=json&baseUrl=https://example.com&includeQueryApi=false&pagingOption=NO_PAGING&resourcePath=/resource/%7BresourceId%7D&ymlProperties=&jsonProperties=%7B%0A%20%20%22key%22:%20%22value%22%0A%7D',
+    'http://localhost:9091/ame/api/generate/open-api-spec?language=en&output=json&baseUrl=https://example.com&includeQueryApi=false&useSemanticVersion=false&pagingOption=NO_PAGING&resourcePath=/resource/%7BresourceId%7D&ymlProperties=&jsonProperties=%7B%0A%20%20%22key%22:%20%22value%22%0A%7D',
     {fixture: 'valid-open-api.json'},
   );
 
   cy.intercept(
     'POST',
-    'http://localhost:9091/ame/api/generate/open-api-spec?language=en&output=yaml&baseUrl=https://example.com&includeQueryApi=false&pagingOption=NO_PAGING&resourcePath=/resource/%7BresourceId%7D&ymlProperties=resourceId:%0A%20%20name:%20resourceId%0A%20%20in:%20path%0A%20%20description:%20An%20example%20resource%20Id.%0A%20%20required:%20true%0A%20%20schema:%0A%20%20%20%20type:%20string%0A&jsonProperties=',
+    'http://localhost:9091/ame/api/generate/open-api-spec?language=en&output=yaml&baseUrl=https://example.com&includeQueryApi=false&useSemanticVersion=false&pagingOption=NO_PAGING&resourcePath=/resource/%7BresourceId%7D&ymlProperties=resourceId:%0A%20%20name:%20resourceId%0A%20%20in:%20path%0A%20%20description:%20An%20example%20resource%20Id.%0A%20%20required:%20true%0A%20%20schema:%0A%20%20%20%20type:%20string%0A&jsonProperties=',
     {fixture: 'valid-open-api.yaml'},
   );
 
@@ -557,6 +563,31 @@ Cypress.Commands.add('openGenerationOpenApiSpec', () => {
   });
 });
 
+Cypress.Commands.add('openGenerationAsyncApiSpec', () => {
+  cy.intercept(
+    'POST',
+    'http://localhost:9091/ame/api/generate/async-api-spec?language=en&output=json&applicationId=application:id&channelAddress=foo/bar&useSemanticVersion=false&writeSeparateFiles=false',
+    {fixture: 'valid-open-api.json'},
+  );
+
+  cy.intercept(
+    'POST',
+    'http://localhost:9091/ame/api/generate/async-api-spec?language=en&output=yaml&applicationId=application:id&channelAddress=foo/bar&useSemanticVersion=false&writeSeparateFiles=false',
+    {fixture: 'valid-open-api.json'},
+  );
+
+  cy.intercept(
+    'POST',
+    'http://localhost:9091/ame/api/generate/async-api-spec?language=en&output=json&applicationId=application:id&channelAddress=foo/bar&useSemanticVersion=false&writeSeparateFiles=true',
+    {fixture: 'valid-open-api.json'},
+  );
+
+  return cy.window().then(win => {
+    const generateHandlingService: GenerateHandlingService = win['angular.generateHandlingService'];
+    return generateHandlingService.openGenerationAsyncApiSpec().afterClosed().subscribe();
+  });
+});
+
 Cypress.Commands.add('openGenerationDocumentation', () => {
   cy.intercept('POST', 'http://localhost:9091/ame/api/generate/documentation?language=en', {fixture: 'valid-documentation.html'});
 

core/apps/ame-e2e/src/support/constants.ts

@@ -138,12 +138,16 @@ export enum SettingsDialogSelectors {
 
 // Generation
 export const GENERATION_tbGenerateOpenApiButton = '[data-cy="tbGenerateOpenApiButton"]';
+export const GENERATION_tbGenerateAsyncApiButton = '[data-cy="tbGenerateAsyncApiButton"]';
 export const GENERATION_tbOutputButton = '[data-cy="tbOutputButton"]';
 export const GENERATION_tbOutputButton_YAML = '[data-cy="tbOutputButton-yaml"]';
 export const GENERATION_tbOutputButton_JSON = '[data-cy="tbOutputButton-json"]';
 export const GENERATION_tbBaseUrlInput = '[data-cy="tbBaseUrlInput"]';
 export const GENERATION_tbBaseUrlInputError = '[data-cy="tbBaseUrlInputError"]';
+export const GENERATION_tbApplicationIdInput = '[data-cy="tbApplicationIdInput"]';
+export const GENERATION_tbChannelAddressInput = '[data-cy="tbChannelAddressInput"]';
 export const GENERATION_activateResourcePathCheckbox = '[data-cy="activateResourcePathCheckbox"]';
+export const GENERATION_writeSeparateFilesCheckbox = '[data-cy="writeSeparateFilesCheckbox"]';
 export const GENERATION_resourcePathTitle = '[data-cy="resourcePathTitle"]';
 export const GENERATION_resourcePathInput = '[data-cy="resourcePathInput"]';
 export const GENERATION_resourcePathRequiredError = '[data-cy="resourcePathRequiredError"]';

core/apps/ame/src/assets/i18n/en.json

@@ -254,10 +254,10 @@
     "OUTPUT_FILE_FORMAT": "Output File format",
     "BASEURL": "Base Url - the base URL for the Aspect API",
     "PLEASE_ADD_VALID_URL": "Please add a valid url",
-    "INCLUDE_QUERY_API_TOOLTIP": "If enabled, a dedicated section for the Query API Endpoint of the Aspect API will be included in the specification.",
+    "INCLUDE_QUERY_API_TOOLTIP": "Include the path for the Query Aspect API Endpoint in the OpenApi specification.",
     "INCLUDE_QUERY_API": "Include Query Api",
     "USE_SEMANTIC_VERSION": "Use Semantic Version",
-    "USE_SEMANTIC_VERSION_TOOLTIP": "If enabled, the complete semantic version of the Aspect Model will be utilized as the API version. Otherwise, only the major part of the Aspect Version will be used as the API version.",
+    "USE_SEMANTIC_VERSION_TOOLTIP": "Use the full semantic version from the Aspect Model as the version for the Aspect API.",
     "ACTIVATE_RESOURCE_PATH": "If enabled, the resource path will be activated in the OpenAPI specification.",
     "ACTIVATE_RESOURCE_PATH_TOOLTIP": "Activate Resource Path",
     "RESOURCE_PATH": "Resource Path - The resource path for the Aspect API endpoints",
@@ -282,6 +282,25 @@
       "GENERATE": "Generate"
     }
   },
+  "GENERATE_ASYNCAPI_SPEC_DIALOG": {
+    "TITLE": "Generate AsyncAPI specification",
+    "GENERATING": "Generate",
+    "CONFIGURATION": "Configuration",
+    "LANGUAGE": "Language",
+    "OUTPUT_FILE_FORMAT": "Output File format",
+    "APPLICATION_ID": "Application ID - sets the application id, e.g. an identifying URL",
+    "CHANNEL_ADDRESS": "Channel Address - sets the channel address (i.e., for MQTT, the topic's name)",
+    "CHANNEL_ADDRESS_ERROR": "Channel address is pattern is not matching",
+    "USE_SEMANTIC_VERSION": "Use Semantic Version",
+    "USE_SEMANTIC_VERSION_TOOLTIP": "Use the full semantic version from the Aspect Model as the version for the Aspect API.",
+    "WRITE_SEPARATE_FILES": "Write Separate Files",
+    "WRITE_SEPARATE_FILES_TOOLTIP": "Package each schema into individual files.",
+    "BUTTON": {
+      "CANCEL": "Cancel",
+      "GENERATE": "Generate"
+    }
+  },
+
   "GENERATE_HANDLING": {
     "FAIL_GENERATE_OPENAPI_SPEC": "Failed to generate Open Api specification",
     "INVALID_MODEL": "Invalid Aspect Model",
@@ -632,6 +651,7 @@
       "LABEL": "Generate",
       "HTML_DOCUMENTATION": "HTML Documentation",
       "OPEN_API_SPECIFICATION": "OpenAPI Specification",
+      "ASYNC_API_SPECIFICATION": "AsyncAPI Specification",
       "AASX_XML": "AASX / XML",
       "SAMPLE_JSON_PAYLOAD": "Sample JSON Payload",
       "JSON_SCHEMA": "JSON Schema"

core/apps/ame/src/assets/img/png/app-menu/disabled/async_FILL0_wght400_GRAD0_opsz24.png

@@ -161,6 +161,10 @@ icons = {
     disabled: `${disabledIconsPath}${path.sep}api_FILL0_wght400_GRAD0_opsz24.png`,
     enabled: `${enabledIconsPath}${path.sep}api_FILL0_wght400_GRAD0_opsz24.png`,
   },
+  GENERATE_ASYNC_API_SPECIFICATION: {
+    disabled: `${disabledIconsPath}${path.sep}async_FILL0_wght400_GRAD0_opsz24.png`,
+    enabled: `${enabledIconsPath}${path.sep}async_FILL0_wght400_GRAD0_opsz24.png`,
+  },
   GENERATE_AASX_XML: {
     disabled: `${disabledIconsPath}${path.sep}data_array_FILL0_wght400_GRAD0_opsz24.png`,
     enabled: `${enabledIconsPath}${path.sep}data_array_FILL0_wght400_GRAD0_opsz24.png`,

core/apps/ame/src/assets/img/png/app-menu/enabled/async_FILL0_wght400_GRAD0_opsz24.png

@@ -90,6 +90,7 @@ module.exports = {
   SIGNAL_VALIDATE_MODEL: 'SIGNAL_VALIDATE_MODEL',
   SIGNAL_GENERATE_HTML_DOCUMENTATION: 'SIGNAL_GENERATE_HTML_DOCUMENTATION',
   SIGNAL_GENERATE_OPEN_API_SPECIFICATION: 'SIGNAL_GENERATE_OPEN_API_SPECIFICATION',
+  SIGNAL_GENERATE_ASYNC_API_SPECIFICATION: 'SIGNAL_GENERATE_ASYNC_API_SPECIFICATION',
   SIGNAL_GENERATE_AASX_XML: 'SIGNAL_GENERATE_AASX_XML',
   SIGNAL_GENERATE_JSON_PAYLOAD: 'SIGNAL_GENERATE_JSON_PAYLOAD',
   SIGNAL_GENERATE_JSON_SCHEMA: 'SIGNAL_GENERATE_JSON_SCHEMA',

core/electron-libs/consts.js

@@ -18,6 +18,7 @@ const {
   SIGNAL_GENERATE_JSON_PAYLOAD,
   SIGNAL_GENERATE_JSON_SCHEMA,
   SIGNAL_GENERATE_OPEN_API_SPECIFICATION,
+  SIGNAL_GENERATE_ASYNC_API_SPECIFICATION,
 } = require('../events');
 const {getIcon} = require('./utils');
 
@@ -35,6 +36,12 @@ function generateSubmenu(translation) {
       icon: getIcon(icons.GENERATE_OPEN_API_SPECIFICATION.enabled),
       click: (menuItem, browserWindow, _) => browserWindow.webContents.send(SIGNAL_GENERATE_OPEN_API_SPECIFICATION),
     },
+    {
+      id: 'GENERATE_ASYNC_API_SPECIFICATION',
+      label: translation.ASYNC_API_SPECIFICATION,
+      icon: getIcon(icons.GENERATE_ASYNC_API_SPECIFICATION.enabled),
+      click: (menuItem, browserWindow, _) => browserWindow.webContents.send(SIGNAL_GENERATE_ASYNC_API_SPECIFICATION),
+    },
     {
       id: 'GENERATE_AASX_XML',
       label: translation.AASX_XML,

core/electron-libs/events.js

@@ -17,7 +17,7 @@ import {catchError, map, mergeMap, retry, tap, timeout} from 'rxjs/operators';
 import {forkJoin, Observable, of, throwError} from 'rxjs';
 import {APP_CONFIG, AppConfig, BrowserService, FileContentModel, HttpHeaderBuilder, LogService} from '@ame/shared';
 import {ModelValidatorService} from './model-validator.service';
-import {OpenApi, ViolationError} from '@ame/editor';
+import {AsyncApi, OpenApi, ViolationError} from '@ame/editor';
 import {removeCommentsFromTTL} from '@ame/utils';
 
 export enum PREDEFINED_MODELS {
@@ -278,6 +278,7 @@ export class ModelApiService {
           output: openApi.output,
           baseUrl: openApi.baseUrl,
           includeQueryApi: openApi.includeQueryApi,
+          useSemanticVersion: openApi.useSemanticVersion,
           pagingOption: openApi.paging,
           resourcePath: openApi.resourcePath,
           ymlProperties: openApi.ymlProperties || '',
@@ -294,6 +295,29 @@ export class ModelApiService {
       );
   }
 
+  generateAsyncApiSpec(rdfContent: string, asyncApi: AsyncApi): Observable<any> {
+    return this.http
+      .post<string>(`${this.serviceUrl}${this.api.generate}/async-api-spec`, rdfContent, {
+        headers: new HttpHeaderBuilder().withContentTypeRdfTurtle().build(),
+        params: {
+          language: asyncApi.language,
+          output: asyncApi.output,
+          applicationId: asyncApi.applicationId,
+          channelAddress: asyncApi.channelAddress,
+          useSemanticVersion: asyncApi.useSemanticVersion,
+          writeSeparateFiles: asyncApi.writeSeparateFiles,
+        },
+        responseType: asyncApi.writeSeparateFiles ? ('blob' as 'json') : asyncApi.output === 'yaml' ? ('text' as 'json') : 'json',
+      })
+      .pipe(
+        timeout(this.requestTimeout),
+        catchError(res => {
+          res.error = asyncApi.output === 'yaml' ? JSON.parse(res.error)?.error : res.error.error;
+          return throwError(() => res);
+        }),
+      );
+  }
+
   downloadDocumentation(rdfContent: string, language: string): Observable<string> {
     return this.http
       .post(`${this.serviceUrl}${this.api.generate}/documentation`, rdfContent, {