feat: adding API serialization

Signed-off-by: Pawel Psztyc <[email protected]>

Author: jarrodek

apis/arc-demo-api/arc-demo-api.raml

@@ -115,6 +115,7 @@ documentation:
   - title: Test doc
     content: Test content
 
+securedBy: [basic]
 
 /test-parameters/{feature}:
   (deprecated): This endpoint is deprecated and will be removed.

apis/petstore/petstore.yaml

@@ -16,6 +16,8 @@ info:
   termsOfService: 'http://swagger.io/terms/'
   contact:
     email: [email protected]
+    name: Swagger IO
+    url: swagger.io
   license:
     name: Apache 2.0
     url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "@api-components/amf-helper-mixin",
   "description": "A mixin with common functions user by most AMF components to compute AMF values",
-  "version": "4.5.12",
+  "version": "4.5.13",
   "license": "Apache-2.0",
   "main": "index.js",
   "module": "index.js",

package.json

@@ -1,4 +1,7 @@
-import { AmfDocument, AsyncApi, DomainElement, Endpoint, Operation, Parameter, Payload, Request, Response, SecurityRequirement, SecurityScheme, Server, Shape, WebApi } from './amf';
+import { 
+  AmfDocument, AsyncApi, DomainElement, EndPoint, Operation, Parameter, Payload, Request, Response, 
+  SecurityRequirement, SecurityScheme, Server, Shape, WebApi, Api
+} from './amf';
 import { Namespace } from './Namespace';
 import { ComputeUriOptions, ServerQueryOptions, ServersQueryOptions } from './types';
 
@@ -281,7 +284,7 @@ interface AmfHelperMixin {
    * @param model AMF data model
    * @returns List of encodes
    */
-  _computeEncodes(model: AmfDocument): DomainElement[]|undefined;
+  _computeEncodes(model: AmfDocument): Api|undefined;
 
   /**
    * Computes list of declarations in the AMF api model.
@@ -376,20 +379,20 @@ interface AmfHelperMixin {
    * @returns Endpoint's URI
    * @deprecated Use `_computeUri()` instead
    */
-  _computeEndpointUri(server: Server, endpoint: Endpoint, baseUri?: string, version?: string): string|undefined;
+  _computeEndpointUri(server: Server, endpoint: EndPoint, baseUri?: string, version?: string): string|undefined;
 
   /**
    * Computes endpoint's URI based on `endpoint` model.
    *
    * @param endpoint Model for the endpoint
    * @param opts Configuration options
    */
-  _computeUri(endpoint: Endpoint, opts?: ComputeUriOptions): string;
+  _computeUri(endpoint: EndPoint, opts?: ComputeUriOptions): string;
 
   /**
    * Appends endpoint's path to the url
    */
-  _appendPath(url: string, endpoint: Endpoint): string;
+  _appendPath(url: string, endpoint: EndPoint): string;
 
   /**
    * Computes base URI value from either `baseUri`, `iron-meta` with
@@ -453,7 +456,7 @@ interface AmfHelperMixin {
    *
    * @returns Always returns an array of endpoints.
    */
-  _computeEndpoints(webApi: WebApi): Endpoint[]|undefined;
+  _computeEndpoints(webApi: WebApi): EndPoint[]|undefined;
 
   /**
    * Computes model for an endpoint documentation.
@@ -462,7 +465,7 @@ interface AmfHelperMixin {
    * @param id Selected shape ID
    * @returns An endpoint definition
    */
-  _computeEndpointModel(webApi: WebApi, id: string): Endpoint|undefined;
+  _computeEndpointModel(webApi: WebApi, id: string): EndPoint|undefined;
 
   /**
    * Computes model for an endpoint documentation using it's path.
@@ -471,7 +474,7 @@ interface AmfHelperMixin {
    * @param path Endpoint path
    * @returns An endpoint definition
    */
-  _computeEndpointByPath(webApi: WebApi, path: string): Endpoint|undefined;
+  _computeEndpointByPath(webApi: WebApi, path: string): EndPoint|undefined;
 
   /**
    * Computes method for the method documentation.
@@ -498,7 +501,7 @@ interface AmfHelperMixin {
    * @param methodId Method id
    * @returns An endpoint model of undefined.
    */
-  _computeMethodEndpoint(webApi: WebApi, methodId: string): Endpoint|undefined;
+  _computeMethodEndpoint(webApi: WebApi, methodId: string): EndPoint|undefined;
 
   /**
    * Computes a list of methods for an endpoint that contains a method with

src/AmfHelperMixin.d.ts

@@ -1,7 +1,25 @@
-/* eslint-disable class-methods-use-this */
-import { AnyShape, ApiKeySettings, ArrayNode, ArrayShape, Callback, CreativeWork, DataArrangeShape, DataNode, DocumentSourceMaps, DomainElement, EndPoint, Example, FileShape, HttpSettings, IriTemplateMapping, NodeShape, OAuth1Settings, OAuth2Flow, OAuth2Settings, ObjectNode, OpenIdConnectSettings, Operation, Parameter, ParametrizedSecurityScheme, Payload, PropertyShape, RecursiveShape, Request, Response, ScalarNode, ScalarShape, SchemaShape, Scope, SecurityRequirement, SecurityScheme, Server, Settings, Shape, SynthesizedField, Tag, TemplatedLink, TupleShape, UnionShape } from "./amf.js";
-import { AmfHelperMixin, expandKey, findAmfType, getArrayItems } from "./AmfHelperMixin.js";
-import { ApiAnyShape, ApiArrayNode, ApiArrayShape, ApiCallback, ApiCustomDomainProperty, ApiDataArrangeShape, ApiDataNode, ApiDataNodeUnion, ApiDocumentation, ApiDocumentSourceMaps, ApiEndPoint, ApiExample, ApiFileShape, ApiIriTemplateMapping, ApiNodeShape, ApiObjectNode, ApiOperation, ApiParameter, ApiParametrizedSecurityScheme, ApiPayload, ApiPropertyShape, ApiRecursiveShape, ApiRequest, ApiResponse, ApiScalarNode, ApiScalarShape, ApiSchemaShape, ApiSecurityApiKeySettings, ApiSecurityHttpSettings, ApiSecurityOAuth1Settings, ApiSecurityOAuth2Flow, ApiSecurityOAuth2Settings, ApiSecurityOpenIdConnectSettings, ApiSecurityRequirement, ApiSecurityScheme, ApiSecurityScope, ApiSecuritySettings, ApiSecuritySettingsUnion, ApiServer, ApiShape, ApiShapeUnion, ApiSynthesizedField, ApiTag, ApiTupleShape, ApiUnionShape, ApiXMLSerializer } from "./types.js";
+import { AmfHelperMixin } from "./AmfHelperMixin.js";
+import {
+  AnyShape, ApiKeySettings, ArrayNode, ArrayShape, Callback, CreativeWork, DataArrangeShape,
+  DataNode, DocumentSourceMaps, DomainElement, EndPoint, Example, FileShape, HttpSettings,
+  IriTemplateMapping, NodeShape, OAuth1Settings, OAuth2Flow, OAuth2Settings, ObjectNode,
+  OpenIdConnectSettings, Operation, Parameter, ParametrizedSecurityScheme, Payload,
+  PropertyShape, RecursiveShape, Request, Response, ScalarNode, ScalarShape, SchemaShape,
+  Scope, SecurityRequirement, SecurityScheme, Server, Settings, Shape, SynthesizedField,
+  Tag, TemplatedLink, TupleShape, UnionShape, Api, WebApi, AsyncApi, Organization, License,
+} from "./amf.js";
+import {
+  ApiAnyShape, ApiArrayNode, ApiArrayShape, ApiCallback, ApiCustomDomainProperty, ApiDataArrangeShape,
+  ApiDataNode, ApiDataNodeUnion, ApiDocumentation, ApiDocumentSourceMaps, ApiEndPoint, ApiExample,
+  ApiFileShape, ApiIriTemplateMapping, ApiNodeShape, ApiObjectNode, ApiOperation, ApiParameter,
+  ApiParametrizedSecurityScheme, ApiPayload, ApiPropertyShape, ApiRecursiveShape, ApiRequest, ApiResponse,
+  ApiScalarNode, ApiScalarShape, ApiSchemaShape, ApiSecurityApiKeySettings, ApiSecurityHttpSettings,
+  ApiSecurityOAuth1Settings, ApiSecurityOAuth2Flow, ApiSecurityOAuth2Settings,
+  ApiSecurityOpenIdConnectSettings, ApiSecurityRequirement, ApiSecurityScheme, ApiSecurityScope,
+  ApiSecuritySettings, ApiSecuritySettingsUnion, ApiServer, ApiShape, ApiShapeUnion, ApiSynthesizedField,
+  ApiTag, ApiTupleShape, ApiUnionShape, ApiXMLSerializer, ApiOrganization, ApiSummary, ApiBase,
+  ApiWeb, ApiAsync, ApiLicense,
+} from "./types.js";
 
 /**
  * A class that takes AMF's ld+json model and outputs JavaScript interface of it.
@@ -11,6 +29,17 @@ export declare class AmfSerializer extends AmfHelperMixin(Object) {
    * @param graph Optional AMF generated graph model.
    */
   constructor(graph?: DomainElement);
+  /**
+   * @param object The API to serialize.
+   * @returns API summary, without complex objects.
+   */
+  apiSummary(object: Api): ApiSummary;
+  api(object: Api): ApiBase;
+  webApi(object: WebApi): ApiWeb;
+  asyncApi(object: AsyncApi): ApiAsync;
+  provider(object: Organization): ApiOrganization;
+  license(object: License): ApiLicense;
+
   /**
    * @param object The AMF Server to serialize.
    * @returns Serialized Server
@@ -143,6 +172,6 @@ export declare class AmfSerializer extends AmfHelperMixin(Object) {
   /**
    * Serializes source maps, when available.
    */
-  sourceMap(object: DocumentSourceMaps): ApiDocumentSourceMaps|undefined;
+  sourceMap(object: DocumentSourceMaps): ApiDocumentSourceMaps | undefined;
   synthesizedField(object: SynthesizedField): ApiSynthesizedField;
 }

src/AmfSerializer.d.ts

@@ -14,7 +14,6 @@ import { AmfHelperMixin, expandKey, findAmfType, getArrayItems } from "./AmfHelp
 /** @typedef {import('./types').ApiEndPoint} ApiEndPoint */
 /** @typedef {import('./types').ApiServer} ApiServer */
 /** @typedef {import('./types').ApiDocumentation} ApiDocumentation */
-/** @typedef {import('./types').SerializedApi} SerializedApi */
 /** @typedef {import('./types').ApiShape} ApiShape */
 /** @typedef {import('./types').ApiPropertyShape} ApiPropertyShape */
 /** @typedef {import('./types').ApiAnyShape} ApiAnyShape */
@@ -54,6 +53,15 @@ import { AmfHelperMixin, expandKey, findAmfType, getArrayItems } from "./AmfHelp
 /** @typedef {import('./types').ApiVariableValue} ApiVariableValue */
 /** @typedef {import('./types').ApiAbstractDeclaration} ApiAbstractDeclaration */
 /** @typedef {import('./types').ShapeProcessingOptions} ShapeProcessingOptions */
+/** @typedef {import('./types').ApiSummary} ApiSummary */
+/** @typedef {import('./types').ApiOrganization} ApiOrganization */
+/** @typedef {import('./types').ApiLicense} ApiLicense */
+/** @typedef {import('./types').ApiBase} ApiBase */
+/** @typedef {import('./types').ApiWeb} ApiWeb */
+/** @typedef {import('./types').ApiAsync} ApiAsync */
+/** @typedef {import('./amf').Api} Api */
+/** @typedef {import('./amf').WebApi} WebApi */
+/** @typedef {import('./amf').AsyncApi} AsyncApi */
 /** @typedef {import('./amf').Server} Server */
 /** @typedef {import('./amf').Parameter} Parameter */
 /** @typedef {import('./amf').Shape} Shape */
@@ -101,6 +109,8 @@ import { AmfHelperMixin, expandKey, findAmfType, getArrayItems } from "./AmfHelp
 /** @typedef {import('./amf').ParametrizedTrait} ParametrizedTrait */
 /** @typedef {import('./amf').VariableValue} VariableValue */
 /** @typedef {import('./amf').AbstractDeclaration} AbstractDeclaration */
+/** @typedef {import('./amf').Organization} Organization */
+/** @typedef {import('./amf').License} License */
 
 /**
  * A class that takes AMF's ld+json model and outputs JavaScript interface of it.
@@ -116,6 +126,167 @@ export class AmfSerializer extends AmfHelperMixin(Object) {
     }
   }
 
+  /**
+   * @param {Api} object The API to serialize.
+   * @returns {ApiSummary} API summary, without complex objects.
+   */
+  apiSummary(object) {
+    const result = /** @type ApiSummary */ ({
+      id: object['@id'],
+      types: object['@type'].map(this[expandKey].bind(this)),
+      customDomainProperties: this.customDomainProperties(object),
+      sourceMaps: this.sourceMap(object),
+      schemes: [],
+      accepts: [],
+      contentType: [],
+      documentations: [],
+      tags: [],
+    });
+    const { ns } = this;
+    const name = this._getValue(object, ns.aml.vocabularies.core.name);
+    if (name && typeof name === 'string') {
+      result.name = name;
+    }
+    const description = this._getValue(object, ns.aml.vocabularies.core.description);
+    if (description && typeof description === 'string') {
+      result.description = description;
+    }
+    const version = this._getValue(object, ns.aml.vocabularies.core.version);
+    if (version && typeof version === 'string') {
+      result.version = version;
+    }
+    const termsOfService = this._getValue(object, ns.aml.vocabularies.core.termsOfService);
+    if (termsOfService && typeof termsOfService === 'string') {
+      result.termsOfService = termsOfService;
+    }
+    const accepts = object[this._getAmfKey(ns.aml.vocabularies.apiContract.accepts)];
+    if (Array.isArray(accepts) && accepts.length) {
+      result.accepts = /** @type string[] */ (this._getValueArray(object, ns.aml.vocabularies.apiContract.accepts));
+    }
+    const contentType = object[this._getAmfKey(ns.aml.vocabularies.apiContract.contentType)];
+    if (Array.isArray(contentType) && contentType.length) {
+      result.contentType = /** @type string[] */ (this._getValueArray(object, ns.aml.vocabularies.apiContract.contentType));
+    }
+    const schemes = object[this._getAmfKey(ns.aml.vocabularies.apiContract.scheme)];
+    if (Array.isArray(schemes) && schemes.length) {
+      result.schemes = /** @type string[] */ (this._getValueArray(object, ns.aml.vocabularies.apiContract.scheme));
+    }
+    let provider = object[this._getAmfKey(ns.aml.vocabularies.core.provider)];
+    if (Array.isArray(provider)) {
+      [provider] = provider;
+    }
+    if (provider) {
+      result.provider = this.provider(provider);
+    }
+    let license = object[this._getAmfKey(ns.aml.vocabularies.core.license)];
+    if (Array.isArray(license)) {
+      [license] = license;
+    }
+    if (license) {
+      result.license = this.license(license);
+    }
+    const tags = object[this._getAmfKey(ns.aml.vocabularies.apiContract.tag)];
+    if (Array.isArray(tags) && tags.length) {
+      result.tags = tags.map(t => this.tag(t));
+    }
+    const docs = object[this._getAmfKey(ns.aml.vocabularies.core.documentation)];
+    if (Array.isArray(docs) && docs.length) {
+      result.documentations = docs.map(d => this.documentation(d));
+    }
+    return result;
+  }
+
+  /**
+   * @param {Api} object 
+   * @returns {ApiBase}
+   */
+  api(object) {
+    const result = /** @type ApiBase */ (this.apiSummary(object));
+    result.endPoints = [];
+    result.servers = [];
+    result.security = [];
+    const { ns } = this;
+    const endPoints = object[this._getAmfKey(ns.aml.vocabularies.apiContract.endpoint)];
+    if (Array.isArray(endPoints) && endPoints.length) {
+      result.endPoints = endPoints.map(e => this.endPoint(e));
+    }
+    const servers = object[this._getAmfKey(ns.aml.vocabularies.apiContract.server)];
+    if (Array.isArray(servers) && servers.length) {
+      result.servers = servers.map(s => this.server(s));
+    }
+    const security = object[this._getAmfKey(ns.aml.vocabularies.security.security)];
+    if (Array.isArray(security) && security.length) {
+      result.security = security.map(s => this.securityRequirement(s));
+    }
+    return result;
+  }
+
+  /**
+   * @param {WebApi} object 
+   * @returns {ApiWeb}
+   */
+  webApi(object) {
+    return this.api(object);
+  }
+
+  /**
+   * @param {AsyncApi} object 
+   * @returns {ApiAsync}
+   */
+  asyncApi(object) {
+    return this.api(object);
+  }
+
+  /**
+   * @param {Organization} object
+   * @returns {ApiOrganization}
+   */
+  provider(object) {
+    const result = /** @type ApiOrganization */ ({
+      id: object['@id'],
+      types: object['@type'].map(this[expandKey].bind(this)),
+      customDomainProperties: this.customDomainProperties(object),
+      sourceMaps: this.sourceMap(object),
+    });
+    const { ns } = this;
+    const name = this._getValue(object, ns.aml.vocabularies.core.name);
+    if (name && typeof name === 'string') {
+      result.name = name;
+    }
+    const url = this._getLinkValue(object, ns.aml.vocabularies.core.url);
+    if (url && typeof url === 'string') {
+      result.url = url;
+    }
+    const email = this._getValue(object, ns.aml.vocabularies.core.email);
+    if (email && typeof email === 'string') {
+      result.email = email;
+    }
+    return result;
+  }
+
+  /**
+   * @param {License} object
+   * @returns {ApiLicense}
+   */
+  license(object) {
+    const result = /** @type ApiLicense */ ({
+      id: object['@id'],
+      types: object['@type'].map(this[expandKey].bind(this)),
+      customDomainProperties: this.customDomainProperties(object),
+      sourceMaps: this.sourceMap(object),
+    });
+    const { ns } = this;
+    const name = this._getValue(object, ns.aml.vocabularies.core.name);
+    if (name && typeof name === 'string') {
+      result.name = name;
+    }
+    const url = this._getLinkValue(object, ns.aml.vocabularies.core.url);
+    if (url && typeof url === 'string') {
+      result.url = url;
+    }
+    return result;
+  }
+
   /**
    * @param {Server} object The AMF Server to serialize.
    * @returns {ApiServer} Serialized Server