@salesforcedevs/docs-components 0.54.0 → 0.54.1-a01

package/src/modules/doc/amfReference/utils.ts

@@ -0,0 +1,669 @@
+import { AmfHelperMixin } from "@api-components/amf-helper-mixin";
+import { normalizeDomId } from "dxUtils/normalizers";
+
+const ID_PROPERTY = "@id";
+const TYPE_PROPERTY = "@type";
+
+export class AmfModelParser extends AmfHelperMixin(Object) {
+    _parsedModel = null;
+
+    constructor(api) {
+        super();
+        if (api) {
+            this.amf = Array.isArray(api) ? api[0] : api;
+        }
+    }
+
+    parse() {
+        let model = this.amf;
+        let data = {};
+        let isFragment = true;
+        const moduleKey = this._getAmfKey(
+            this.ns.aml.vocabularies.document.Module
+        );
+        if (this._hasType(model, this.ns.aml.vocabularies.document.Document)) {
+            isFragment = false;
+            model = this._ensureAmfModel(model);
+            data = this._collectData(model);
+        } else if (
+            this._hasType(
+                model,
+                this.ns.aml.vocabularies.security.SecuritySchemeFragment
+            )
+        ) {
+            data = this._collectSecurityData(model);
+        } else if (
+            this._hasType(
+                model,
+                this.ns.aml.vocabularies.apiContract.UserDocumentationFragment
+            )
+        ) {
+            data = this._collectDocumentationData(model);
+        } else if (
+            this._hasType(
+                model,
+                this.ns.aml.vocabularies.shapes.DataTypeFragment
+            )
+        ) {
+            data = this._collectTypeData(model);
+        } else if (
+            model[TYPE_PROPERTY] &&
+            moduleKey === model[TYPE_PROPERTY][0]
+        ) {
+            data = this._collectData(model);
+        }
+
+        this._collectName(model, data);
+
+        const summaryId = data.title + "Summary";
+
+        return {
+            title: data.title,
+            summary: {
+                id: summaryId,
+                label: "Summary",
+                domId: normalizeDomId(summaryId)
+            },
+            types: data.types,
+            security: data.securitySchemes,
+            endpoints: data.endpoints,
+            docs: data.documentation,
+            isFragment
+        };
+    }
+
+    get parsedModel() {
+        if (!this._parsedModel) {
+            this._parsedModel = this.parse();
+        }
+
+        return this._parsedModel;
+    }
+
+    /**
+     * Collects the information about the API and creates data model
+     * for the navigation element
+     *
+     * @param {object} model
+     * @return {Object} Data model for the API navigation
+     */
+    _collectData(model) {
+        const result = {
+            documentation: [],
+            types: [],
+            securitySchemes: [],
+            endpoints: []
+        };
+        if (!model) {
+            return result;
+        }
+        result._typeIds = [];
+        result._basePaths = [];
+        this._traverseDeclarations(model, result);
+        this._traverseReferences(model, result);
+        this._traverseEncodes(model, result);
+        delete result._typeIds;
+        delete result._basePaths;
+        return result;
+    }
+
+    /**
+     * Collects the data from the security fragment
+     * @param {object} model Security fragment model
+     * @return {Object|undefined}
+     */
+    _collectSecurityData(model) {
+        const result = {
+            securitySchemes: []
+        };
+        const encodes = this._computeEncodes(model);
+        if (!encodes) {
+            return undefined;
+        }
+        this._appendSecurityItem(encodes, result);
+        return result;
+    }
+
+    /**
+     * Collects the data from the documentation fragment
+     * @param {object} model Documentation fragment model
+     * @return {Object|undefined}
+     */
+    _collectDocumentationData(model) {
+        const result = {
+            documentation: []
+        };
+        const encodes = this._computeEncodes(model);
+        if (!encodes) {
+            return undefined;
+        }
+        this._appendDocumentationItem(encodes, result);
+        return result;
+    }
+
+    /**
+     * Collects the data from the type fragment
+     * @param {object} model Type fragment model
+     * @return {Object|undefined}
+     */
+    _collectTypeData(model) {
+        const result = {
+            types: [],
+            _typeIds: []
+        };
+        const encodes = this._computeEncodes(model);
+        if (!encodes) {
+            return undefined;
+        }
+        this._appendTypeItem(encodes, result);
+        delete result._typeIds;
+        return result;
+    }
+
+    /**
+     * Traverses the `http://raml.org/vocabularies/document#declares`
+     * node to find types and security schemes.
+     *
+     * @param {object} model AMF model
+     * @param {TargetModel} target Target object where to put data.
+     */
+    _traverseDeclarations(model, target) {
+        const declares = this._computeDeclares(model);
+        if (!declares) {
+            return;
+        }
+        declares.forEach((item) => this._appendModelItem(item, target));
+    }
+
+    /**
+     * Traverses the `http://raml.org/vocabularies/document#references`
+     *
+     * @param {object} model AMF model
+     * @param {TargetModel} target Target object where to put data.
+     */
+    _traverseReferences(model, target) {
+        const refs = this._computeReferences(model);
+        if (!refs) {
+            return;
+        }
+        refs.forEach((item) => {
+            if (
+                !this._hasType(item, this.ns.aml.vocabularies.document.Module)
+            ) {
+                return;
+            }
+            this._traverseDeclarations(item, target);
+        });
+    }
+
+    /**
+     * Traverses the `http://raml.org/vocabularies/document#encodes`
+     * node to find documentation and endpoints.
+     *
+     * @param {object} model AMF model
+     * @param {TargetModel} target Target object where to put data.
+     */
+    _traverseEncodes(model, target) {
+        const webApi = this._computeWebApi(model);
+        const endpoints = this._computeEndpoints(webApi);
+
+        if (endpoints) {
+            endpoints.forEach((item) => this._appendModelItem(item, target));
+        }
+        const dkey = this._getAmfKey(
+            this.ns.aml.vocabularies.core.documentation
+        );
+        const documentation = this._ensureArray(webApi[dkey]);
+        if (documentation) {
+            documentation.forEach((item) =>
+                this._appendModelItem(item, target)
+            );
+        }
+    }
+
+    /**
+     * Extract API title from `http://raml.org/vocabularies/document#encodes`
+     *
+     * @param {object} model AMF model
+     * @param {TargetModel} target Target object where to put data.
+     */
+    _collectName(model, target) {
+        const encodes = this._computeEncodes(model);
+        if (!encodes) {
+            return;
+        }
+
+        target.title = this._getValue(
+            encodes,
+            this._getAmfKey(this.ns.aml.vocabularies.core.name)
+        );
+    }
+
+    /**
+     * Appends declaration of navigation data model to the target if
+     * it matches documentation or security types.
+     *
+     * @param {Object} item AMF model item to check for data.
+     * @param {TargetModel} target The target to which append values.
+     * @return {void}
+     */
+    _appendModelItem(item, target) {
+        if (this._hasType(item, this.ns.w3.shacl.Shape)) {
+            this._appendTypeItem(item, target);
+        } else if (
+            this._hasType(
+                item,
+                this.ns.aml.vocabularies.security.SecurityScheme
+            )
+        ) {
+            this._appendSecurityItem(item, target);
+        } else if (
+            this._hasType(item, this.ns.aml.vocabularies.core.CreativeWork)
+        ) {
+            this._appendDocumentationItem(item, target);
+        } else if (
+            this._hasType(item, this.ns.aml.vocabularies.apiContract.EndPoint)
+        ) {
+            this._appendEndpointItem(item, target);
+        }
+    }
+
+    /**
+     * Appends "type" item to the results.
+     *
+     * @param {Object} item Type item declaration
+     * @param {TargetModel} target
+     * @return {void}
+     */
+    _appendTypeItem(item, target) {
+        const w3name = this._getValue(item, this.ns.w3.shacl.name);
+        if (w3name && w3name.indexOf("amf_inline_type") === 0) {
+            // https://www.mulesoft.org/jira/browse/APIMF-972
+            return;
+        }
+        let name = this._getValue(item, this.ns.aml.vocabularies.core.name);
+        if (!name && w3name) {
+            name = w3name;
+        } else if (!name) {
+            return;
+        }
+        const id = item[ID_PROPERTY];
+        if (!id) {
+            return;
+        }
+        const rfIdKey = this._getAmfKey(
+            this.ns.aml.vocabularies.document.referenceId
+        );
+        const compareId = id;
+        const refNode = this._ensureArray(item[rfIdKey]);
+        const refId = refNode ? refNode[0][ID_PROPERTY] : undefined;
+        const idIndex = target._typeIds.indexOf(compareId);
+        const refIndex = refId ? target._typeIds.indexOf(refId) : -1;
+        if (idIndex === -1 && refIndex === -1) {
+            target._typeIds[target._typeIds.length] = id;
+            if (refId) {
+                target._typeIds[target._typeIds.length] = refId;
+            }
+            target.types.push({
+                label: name,
+                id,
+                domId: normalizeDomId(id)
+            });
+        }
+    }
+
+    /**
+     * Appends "security" item to the results.
+     *
+     * @param {Object} item Type item declaration
+     * @param {TargetModel} target
+     * @return {void}
+     */
+    _appendSecurityItem(item, target) {
+        const voc = this.ns.aml.vocabularies;
+        let name = this._getValue(item, voc.core.displayName);
+        if (!name) {
+            name = this._getValue(item, voc.security.name);
+        }
+        if (!name) {
+            const apiName = this._getValue(item, voc.core.name);
+            const secType = this._getValue(item, voc.security.type);
+            let result = "";
+            if (apiName) {
+                result = `${apiName} - `;
+            }
+            name = result + this._mapAuthName(secType);
+        }
+        const id = item[ID_PROPERTY];
+        target.securitySchemes.push({
+            label: String(name),
+            id,
+            domId: normalizeDomId(id)
+        });
+    }
+
+    /**
+     * Maps authorization scheme name to a label
+     * @param {string} name
+     * @return {string}
+     */
+    _mapAuthName(name) {
+        switch (name) {
+            case "http":
+                return "HTTP";
+            case "openIdConnect":
+                return "OpenID Connect";
+            default:
+                return name;
+        }
+    }
+
+    /**
+     * Checks if url is valid and return it, otherwise returns 'about:blank'.
+     * @param {string} url
+     * @return {string}
+     */
+    _validUrl(url) {
+        return url.startsWith("http://") || url.startsWith("https://")
+            ? url
+            : "about:blank";
+    }
+
+    /**
+     * Appends "documentation" item to the results.
+     *
+     * @param {Object} item Type item declaration
+     * @param {TargetModel} target
+     * @return {void}
+     */
+    _appendDocumentationItem(item, target) {
+        const { core } = this.ns.aml.vocabularies;
+        const id = item[ID_PROPERTY];
+        const urlNode = item[this._getAmfKey(core.url)];
+        const title = this._getValue(item, core.title);
+        const description = this._getValue(item, core.description);
+        const label = title ? String(title) : String(description);
+        let isExternal = false;
+        let url = urlNode ? (urlNode[0] || urlNode)[ID_PROPERTY] : undefined;
+        if (url) {
+            url = this._validUrl(url);
+            isExternal = true;
+        }
+        const result = {
+            id,
+            label,
+            isExternal,
+            url,
+            domId: normalizeDomId(id)
+        };
+        target.documentation.push(result);
+    }
+
+    /**
+     * Appends "endpoint" item to the results.
+     * This also iterates over methods to extract method data.
+     *
+     * @param {Object} item Endpoint item declaration
+     * @param {TargetModel} target
+     * @return {void}
+     */
+    _appendEndpointItem(item, target) {
+        const result = {};
+
+        let name = this._getValue(item, this.ns.aml.vocabularies.core.name);
+        const path = this._getValue(
+            item,
+            this.ns.raml.vocabularies.apiContract.path
+        );
+        result.path = path;
+
+        let tmpPath = path;
+        if (tmpPath[0] === "/") {
+            tmpPath = tmpPath.substr(1);
+        }
+        const parts = tmpPath.split("/");
+        let indent = 0;
+        target._basePaths[target._basePaths.length] = path;
+        if (parts.length > 1) {
+            const lowerParts = parts.slice(0, parts.length - 1);
+            if (lowerParts.length) {
+                for (let i = lowerParts.length - 1; i >= 0; i--) {
+                    const currentPath = `/${lowerParts
+                        .slice(0, i + 1)
+                        .join("/")}`;
+                    if (target._basePaths.indexOf(currentPath) !== -1) {
+                        indent++;
+                    }
+                }
+            }
+        }
+        if (!name) {
+            result.renderPath = false;
+            if (indent > 0) {
+                try {
+                    name = this._computePathName(
+                        path,
+                        parts,
+                        indent,
+                        target._basePaths
+                    );
+                } catch (_) {
+                    name = path;
+                }
+            } else {
+                name = path;
+            }
+        } else {
+            result.renderPath = true;
+        }
+        const id = item[ID_PROPERTY];
+        const key = this._getAmfKey(this.ns.w3.hydra.supportedOperation);
+        const operations = this._ensureArray(item[key]) || [];
+        const methods = operations.map((op) => this._createOperationModel(op));
+        result.label = String(name);
+        result.id = id;
+        result.indent = indent;
+        result.methods = methods;
+        result.domId = normalizeDomId(id);
+        target.endpoints.push(result);
+    }
+
+    /**
+     * Computes label for an endpoint when name is missing and the endpoint
+     * is indented, hence name should be truncated.
+     * @param {string} currentPath Endpoint's path
+     * @param {string[]} parts Path parts
+     * @param {number} indent Endpoint indentation
+     * @param {string[]} basePaths List of base paths already used.
+     * @return {string} Name of the path to render.
+     */
+    _computePathName(currentPath, parts, indent, basePaths) {
+        let path = "";
+        for (let i = 0, len = parts.length; i < len; i++) {
+            path += `/${parts[i]}`;
+            if (basePaths.indexOf(path) !== -1) {
+                indent--;
+            }
+            if (indent === 0) {
+                break;
+            }
+        }
+        return currentPath.replace(path, "");
+    }
+
+    /**
+     * Creates the view model for an opration.
+     *
+     * @param {Object} item Operation AMF model
+     * @return {Object} Method view model
+     */
+    _createOperationModel(item) {
+        const label = this._getValue(item, this.ns.aml.vocabularies.core.name);
+        const methodKey = this.ns.aml.vocabularies.apiContract.method;
+        const id = item[ID_PROPERTY];
+        const method = this._getValue(item, methodKey);
+        return {
+            label,
+            id,
+            method,
+            domId: normalizeDomId(id)
+        };
+    }
+
+    /**
+     * Computes Endpoint definition model from web API and current selection.
+     *
+     * @param {any} model WebApi AMF model. Do not use an array here.
+     * @param {string} selected Currently selected `@id`.
+     * @return {any|undefined} Model definition for an endpoint fragment.
+     */
+    computeEndpointApiModel(model, selectedId) {
+        const webApi = this._computeApi(model);
+        return this._computeEndpointModel(webApi, selectedId);
+    }
+
+    /**
+     * Computes Method definition model from web API and current selection.
+     *
+     * @param {any} model WebApi AMF model. Do not use an array here.
+     * @param {string} selected Currently selected `@id`.
+     * @return {any|undefined} Model definition for an endpoint fragment.
+     */
+    computeMethodApiModel(model, selected) {
+        const webApi = this._computeApi(model);
+        return this._computeMethodModel(webApi, selected);
+    }
+
+    /**
+     * Computes Endpoint definition model for a method from web API and current selection.
+     *
+     * @param {any} model WebApi AMF model. Do not use an array here.
+     * @param {string} selected Currently selected `@id`.
+     * @return {any|undefined} Model definition for an endpoint fragment.
+     */
+    computeEndpointApiMethodModel(model, selected) {
+        const webApi = this._computeApi(model);
+        return this._computeMethodEndpoint(webApi, selected);
+    }
+
+    /**
+     * Computes security scheme definition model from web API and current selection.
+     * It looks for the definition in both `declares` and `references` properties.
+     * Returned value is already resolved AMF model (references are resolved).
+     *
+     * @param {any} model WebApi AMF model. Do not use an array here.
+     * @param {string} selected Currently selected `@id`.
+     * @return {any|undefined} Model definition for the security scheme.
+     */
+    computeSecurityApiModel(model, selected) {
+        const declares = this._computeDeclares(model);
+        let result;
+        if (declares) {
+            result = declares.find((item) => item["@id"] === selected);
+        }
+        if (!result) {
+            const references = this._computeReferences(model);
+            if (references && references.length) {
+                for (let i = 0, len = references.length; i < len; i++) {
+                    if (
+                        !this._hasType(
+                            references[i],
+                            this.ns.aml.vocabularies.document.Module
+                        )
+                    ) {
+                        continue;
+                    }
+                    result = this._computeReferenceSecurity(
+                        references[i],
+                        selected
+                    );
+                    if (result) {
+                        break;
+                    }
+                }
+            }
+        } else {
+            result = this._resolve(result);
+        }
+        return result;
+    }
+
+    /**
+     * Computes documentation definition model from web API and current selection.
+     *
+     * @param {any} model WebApi AMF model. Do not use an array here.
+     * @param {string} selected Currently selected `@id`.
+     * @return {any|undefined} Model definition for a documentation fragment.
+     */
+    computeDocsApiModel(model, selected) {
+        const webApi = this._computeApi(model);
+        return this._computeDocument(webApi, selected);
+    }
+
+    /**
+     * Computes type definition model from web API and current selection.
+     * It looks for the definition in both `declares` and `references` properties.
+     * Returned value is already resolved AMF model (references are resolved).
+     *
+     * @param {any} model WebApi AMF model. Do not use an array here.
+     * @param {string} selected Currently selected `@id`.
+     * @return {any|undefined} Model definition for a type.
+     */
+    computeTypeApiModel(model, selected) {
+        const declares = this._computeDeclares(model);
+        const references = this._computeReferences(model);
+        return this._computeType(declares, references, selected);
+    }
+
+    /**
+     * Computes a security model from a reference (library for example).
+     * @param {any|any[]} reference AMF model for a reference to extract the data from
+     * @param {string} selected Node ID to look for
+     * @return {any|undefined} Type definition or undefined if not found.
+     */
+    _computeReferenceSecurity(reference, selected) {
+        const declare = this._computeDeclares(reference);
+        if (!declare) {
+            return undefined;
+        }
+        let result = declare.find((item) => {
+            if (Array.isArray(item)) {
+                [item] = item;
+            }
+            return item["@id"] === selected;
+        });
+        if (Array.isArray(result)) {
+            [result] = result;
+        }
+        return this._resolve(result);
+    }
+
+    /**
+     * Computes API's media types when requesting type documentation view.
+     * This is passed to the type documentation to render examples in the type
+     * according to API's defined media type.
+     *
+     * @param {any} model API model.
+     * @return {string[]|undefined} List of supported media types or undefined.
+     */
+    computeApiMediaTypes(model) {
+        if (Array.isArray(model)) {
+            [model] = model;
+        }
+        let webApi = this._computeWebApi(model);
+        if (!webApi) {
+            return undefined;
+        }
+        if (Array.isArray(webApi)) {
+            [webApi] = webApi;
+        }
+        const key = this._getAmfKey(
+            this.ns.aml.vocabularies.apiContract.accepts
+        );
+        const value = this._ensureArray(webApi[key]);
+        if (value) {
+            return value.map((item) => item["@value"]);
+        }
+        return undefined;
+    }
+}

package/src/modules/doc/amfTopic/amfTopic.css

@@ -0,0 +1 @@
+@import "docHelpers/amfStyle";

package/src/modules/doc/amfTopic/amfTopic.html

@@ -0,0 +1,3 @@
+<template>
+    <div class="topic-container" lwc:dom="manual"></div>
+</template>