@atlassian/atlassian-openapi 1.0.3

package/README.md

@@ -0,0 +1,15 @@
+# atlassian-openapi
+
+This package contains Typescript typings for OpenAPI 3.0 with Atlassian extensions included as well as 
+convenience functions for dealing with OpenAPI 3.0.
+
+Atlassian code and tooling that is based on OpenAPI 3.0 should use this library.
+
+Specifically, it includes:
+
+ - A `Swagger` namespace with OpenAPI 3.0 types.
+ - A `Lookup` class to let you easily resolve `$ref`s within your OpenAPI files.
+ - OpenAPI Operation Grouping logic that mirrors developer.atlassian.com's Side Nav and Postman collections.
+ - Type Checking functions to let you differentiate between different types.
+
+Enjoy!

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export * from './swagger';
+export * from './lookup';
+export * from './type-checks';
+export * from './operation-grouping';

package/lib/index.js

@@ -0,0 +1,16 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !exports.hasOwnProperty(p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./swagger"), exports);
+__exportStar(require("./lookup"), exports);
+__exportStar(require("./type-checks"), exports);
+__exportStar(require("./operation-grouping"), exports);

package/lib/lookup.d.ts

@@ -0,0 +1,50 @@
+import { Swagger as S } from './swagger';
+export declare namespace SwaggerLookup {
+    /**
+     * Given an object and a potential reference to that object, this interface will help you perform that
+     * lookup and either return the right object or undefined.
+     */
+    interface Lookup {
+        getCallback: (c: S.Callback | S.Reference) => S.Callback | undefined;
+        getExample: (e: S.Example | S.Reference) => S.Example | undefined;
+        getHeaders: (h: S.Header | S.Reference) => S.Header | undefined;
+        getLink: (l: S.Link | S.Reference) => S.Link | undefined;
+        getParam: (p: S.ParameterOrRef) => S.Parameter | undefined;
+        getRequestBody: (b: S.RequestBody | S.Reference) => S.RequestBody | undefined;
+        getResponse: (r: S.Response | S.Reference) => S.Response | undefined;
+        getSchema: (s: S.Schema | S.Reference) => S.Schema | undefined;
+        getSecuritySchemeByName: (name: string) => S.SecurityScheme | undefined;
+        getSecurityScheme: (ss: S.SecurityScheme | S.Reference) => S.SecurityScheme | undefined;
+    }
+    /**
+     * This lookup does not return any values that could be discovered via references. Every function
+     * just operates as the ID function; thus the name.
+     */
+    class IdLookup implements Lookup {
+        getExample(e: S.Example | S.Reference): S.Example | undefined;
+        getRequestBody(b: S.Reference | S.RequestBody): S.RequestBody | undefined;
+        getHeaders(h: S.Reference | S.Header): S.Header | undefined;
+        getSecuritySchemeByName(_name: string): S.SecurityScheme | undefined;
+        getSecurityScheme(ss: S.Reference | S.SecurityScheme): S.SecurityScheme | undefined;
+        getLink(l: S.Reference | S.Link): S.Link | undefined;
+        getCallback(c: S.Reference | S.Callback): S.Callback | undefined;
+        getResponse(r: S.Response | S.Reference): S.Response | undefined;
+        getSchema(s: S.Schema | S.Reference): S.Schema | undefined;
+        getParam(p: S.ParameterOrRef): S.Parameter | undefined;
+    }
+    class InternalLookup implements Lookup {
+        private schema;
+        constructor(swagger: S.SwaggerV3);
+        getCallback(c: S.Reference | S.Callback): S.Callback | undefined;
+        getExample(e: S.Example | S.Reference): S.Example | undefined;
+        getHeaders(h: S.Reference | S.Header): S.Header | undefined;
+        getLink(l: S.Reference | S.Link): S.Link | undefined;
+        getParam(p: S.ParameterOrRef): S.Parameter | undefined;
+        getRequestBody(b: S.Reference | S.RequestBody): S.RequestBody | undefined;
+        getResponse(r: S.Response | S.Reference): S.Response | undefined;
+        getSchema(s: S.Schema | S.Reference): S.Schema | undefined;
+        getSecuritySchemeByName(name: string): S.SecurityScheme | undefined;
+        getSecurityScheme(ss: S.Reference | S.SecurityScheme): S.SecurityScheme | undefined;
+        private performLookup;
+    }
+}

package/lib/lookup.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwaggerLookup = void 0;
+const type_checks_1 = require("./type-checks");
+const jsonpointer_1 = require("jsonpointer");
+var SwaggerLookup;
+(function (SwaggerLookup) {
+    /**
+     * This lookup does not return any values that could be discovered via references. Every function
+     * just operates as the ID function; thus the name.
+     */
+    class IdLookup {
+        getExample(e) {
+            return !type_checks_1.SwaggerTypeChecks.isReference(e) ? e : undefined;
+        }
+        getRequestBody(b) {
+            return !type_checks_1.SwaggerTypeChecks.isReference(b) ? b : undefined;
+        }
+        getHeaders(h) {
+            return !type_checks_1.SwaggerTypeChecks.isReference(h) ? h : undefined;
+        }
+        getSecuritySchemeByName(_name) {
+            return undefined;
+        }
+        getSecurityScheme(ss) {
+            return !type_checks_1.SwaggerTypeChecks.isReference(ss) ? ss : undefined;
+        }
+        getLink(l) {
+            return !type_checks_1.SwaggerTypeChecks.isReference(l) ? l : undefined;
+        }
+        getCallback(c) {
+            return !type_checks_1.SwaggerTypeChecks.isReference(c) ? c : undefined;
+        }
+        getResponse(r) {
+            return !type_checks_1.SwaggerTypeChecks.isReference(r) ? r : undefined;
+        }
+        getSchema(s) {
+            return !type_checks_1.SwaggerTypeChecks.isReference(s) ? s : undefined;
+        }
+        getParam(p) {
+            return !type_checks_1.SwaggerTypeChecks.isReference(p) ? p : undefined;
+        }
+    }
+    SwaggerLookup.IdLookup = IdLookup;
+    class InternalLookup {
+        constructor(swagger) {
+            this.schema = swagger;
+        }
+        getCallback(c) {
+            return this.performLookup(c, type_checks_1.SwaggerTypeChecks.isCallback);
+        }
+        getExample(e) {
+            return this.performLookup(e, type_checks_1.SwaggerTypeChecks.isExample);
+        }
+        getHeaders(h) {
+            return this.performLookup(h, type_checks_1.SwaggerTypeChecks.isHeader);
+        }
+        getLink(l) {
+            return this.performLookup(l, type_checks_1.SwaggerTypeChecks.isLink);
+        }
+        getParam(p) {
+            return this.performLookup(p, type_checks_1.SwaggerTypeChecks.isParameter);
+        }
+        getRequestBody(b) {
+            return this.performLookup(b, type_checks_1.SwaggerTypeChecks.isRequestBody);
+        }
+        getResponse(r) {
+            return this.performLookup(r, type_checks_1.SwaggerTypeChecks.isResponse);
+        }
+        getSchema(s) {
+            const potentialSchema = this.performLookup(s, type_checks_1.SwaggerTypeChecks.isSchema);
+            // Use the definition name if the title is missing
+            if (typeof potentialSchema !== 'undefined'
+                && typeof potentialSchema.title === 'undefined'
+                && type_checks_1.SwaggerTypeChecks.isReference(s)) {
+                const refSplit = s.$ref.split('/');
+                if (refSplit.length === 4) {
+                    return Object.assign(Object.assign({}, potentialSchema), { title: refSplit[3] });
+                }
+            }
+            return potentialSchema;
+        }
+        getSecuritySchemeByName(name) {
+            return this.getSecurityScheme({ '$ref': `#/components/securitySchemes/${name}` });
+        }
+        getSecurityScheme(ss) {
+            return this.performLookup(ss, type_checks_1.SwaggerTypeChecks.isSecurityScheme);
+        }
+        // tslint:disable-next-line:no-any
+        performLookup(o, tCheck) {
+            if (!type_checks_1.SwaggerTypeChecks.isReference(o)) {
+                return o;
+            }
+            const ref = o.$ref;
+            if (!ref.startsWith('#')) {
+                // Any references that don't start with a # are external, and thus not handled
+                return undefined;
+            }
+            const result = jsonpointer_1.get(this.schema, ref.slice(1));
+            // Call recursively if you perform a lookup and get another reference
+            if (type_checks_1.SwaggerTypeChecks.isReference(result)) {
+                return this.performLookup(result, tCheck);
+            }
+            return tCheck(result) ? result : undefined;
+        }
+    }
+    SwaggerLookup.InternalLookup = InternalLookup;
+})(SwaggerLookup = exports.SwaggerLookup || (exports.SwaggerLookup = {}));

package/lib/operation-grouping.d.ts

@@ -0,0 +1,28 @@
+import { Swagger } from './swagger';
+export declare type PathAndOperation = {
+    baseUrl: string;
+    path: string;
+    method: Swagger.Method;
+    operation: Swagger.Operation;
+    pathItemParameters: (Swagger.ParameterOrRef)[];
+    security: Swagger.SecurityRequirement[] | undefined;
+};
+export declare type OperationGrouping = {
+    title: string;
+    description?: string;
+    operations: PathAndOperation[];
+};
+export declare type OperationGroupings = {
+    groups: OperationGrouping[];
+};
+export declare function getIdForOperationGroup(grouping: OperationGrouping): string;
+export declare function getIdForOperation(po: PathAndOperation): string;
+export declare function getOpPath(po: PathAndOperation): string;
+export declare type GroupingStrategy = (swagger: Swagger.SwaggerV3) => OperationGroupings;
+/**
+ * This function replicates the RAD V1 grouping strategy that we used for the side-nav. Having this grouping strategy
+ * present should ease the transition to RAD V2 by making it the fallback mechanism if tagging has not been implemented.
+ */
+export declare const radV1GroupingStrategy: GroupingStrategy;
+export declare const urlGroupingStrategy: GroupingStrategy;
+export declare const tagGroupingStrategy: GroupingStrategy;

package/lib/operation-grouping.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tagGroupingStrategy = exports.urlGroupingStrategy = exports.radV1GroupingStrategy = exports.getOpPath = exports.getIdForOperation = exports.getIdForOperationGroup = void 0;
+const URI = require("urijs");
+function findBestServer(swagger) {
+    if (swagger.servers === undefined) {
+        return undefined;
+    }
+    const validServers = swagger.servers.filter(s => s.url.startsWith('http'));
+    if (validServers.length === 0) {
+        return swagger.servers.length > 0 ? swagger.servers[0] : undefined;
+    }
+    const httpsServer = validServers.find(s => s.url.startsWith('https://'));
+    return httpsServer === undefined ? validServers[0] : httpsServer;
+}
+function getServerUrlWithDefault(swagger) {
+    const bestServer = findBestServer(swagger);
+    // Default value
+    if (bestServer === undefined) {
+        return 'https://your-domain.atlassian.net';
+    }
+    return bestServer.url.startsWith('//') ? `https:${bestServer.url}` : bestServer.url;
+}
+function getIdForOperationGroup(grouping) {
+    // In the end, only alphanumeric characters should remain
+    return 'api-group-' + grouping.title.replace(/[^A-Za-z\-]/g, '-');
+}
+exports.getIdForOperationGroup = getIdForOperationGroup;
+function generateId(text) {
+    return text.replace(/[^a-z0-9]+/gi, '-').replace(/^-|-$/g, '');
+}
+function getIdForOperation(po) {
+    return `api-${generateId(po.path.substring(1))}-${po.method}`;
+}
+exports.getIdForOperation = getIdForOperation;
+function getOpPath(po) {
+    const pathSegments = new URI(po.baseUrl).segment();
+    const basePath = pathSegments.filter(s => s.length > 0).join('/');
+    const path = basePath.length > 0 ? `/${basePath}${po.path}` : po.path;
+    return `${po.method.toUpperCase()} ${path}`;
+}
+exports.getOpPath = getOpPath;
+function pathItemHasSummary(pathItem) {
+    return typeof pathItem.summary !== 'undefined' && pathItem.summary.length > 0;
+}
+function extractFromPathItem(baseUrl, path, pathItem, security) {
+    const pathItemParameters = pathItem.parameters === undefined ? [] : pathItem.parameters;
+    const toPO = (method, operation) => {
+        return {
+            baseUrl,
+            path,
+            method,
+            operation,
+            pathItemParameters,
+            security
+        };
+    };
+    const operations = new Array();
+    // tslint:disable:no-unused-expression
+    pathItem.get && operations.push(toPO('get', pathItem.get));
+    pathItem.put && operations.push(toPO('put', pathItem.put));
+    pathItem.post && operations.push(toPO('post', pathItem.post));
+    pathItem.delete && operations.push(toPO('delete', pathItem.delete));
+    pathItem.options && operations.push(toPO('options', pathItem.options));
+    pathItem.head && operations.push(toPO('head', pathItem.head));
+    pathItem.patch && operations.push(toPO('patch', pathItem.patch));
+    pathItem.trace && operations.push(toPO('trace', pathItem.trace));
+    // tslint:enable:no-unused-expression
+    return operations;
+}
+function toPathAndOperation(baseUrl, paths, security) {
+    return new Array().concat(...Object.keys(paths).map(path => extractFromPathItem(baseUrl, path, paths[path], security)));
+}
+function toTagGroups(tags, pos) {
+    let lookup = {};
+    let defaultOps = new Array();
+    // For each path and operation
+    pos.forEach(op => {
+        // If there is no tag, put it in the default group
+        if (typeof op.operation.tags === 'undefined' || op.operation.tags.length === 0) {
+            defaultOps.push(op);
+        }
+        else {
+            const firstTag = op.operation.tags[0];
+            const matchingTag = tags.find(t => t.name === firstTag);
+            // If there is a tag but it does not match any defined tag, put it in the default group
+            if (typeof matchingTag !== 'undefined') {
+                if (typeof lookup[firstTag] === 'undefined') {
+                    const opArr = new Array();
+                    opArr.push(op);
+                    lookup[firstTag] = {
+                        tag: matchingTag,
+                        operations: opArr
+                    };
+                }
+                else {
+                    lookup[firstTag].operations.push(op);
+                }
+            }
+            else {
+                defaultOps.push(op);
+            }
+        }
+    });
+    return {
+        // Maintain the original sort order of the tags
+        groups: tags.map(t => lookup[t.name]).filter(tg => typeof tg !== 'undefined'),
+        default: {
+            operations: defaultOps
+        }
+    };
+}
+function tagGroupToOperationGrouping(tg) {
+    return {
+        title: tg.tag.name,
+        description: tg.tag.description,
+        operations: tg.operations
+    };
+}
+function tagGroupsToOperationGroupings(tgs) {
+    const groups = tgs.groups.map(tagGroupToOperationGrouping);
+    if (tgs.default.operations.length > 0) {
+        groups.push({
+            title: 'Other operations',
+            operations: tgs.default.operations
+        });
+    }
+    return { groups };
+}
+function generateTitleFromPath(path) {
+    // This is a workaround for the issue with deeper endpoint paths in Jira Cloud REST Api.
+    // This should be replaced with tags feature, once it's implemented. See go/j/JCE-1590
+    const pathElement = path.startsWith('/api/3/') || path.startsWith('/api/2/') || path.startsWith('/auth/1') ? 2 : 0;
+    const firstPathItem = path.substring(1).split('/')[pathElement];
+    return firstPathItem ? firstPathItem[0].toUpperCase() + firstPathItem.slice(1) : '/';
+}
+/**
+ * This function replicates the RAD V1 grouping strategy that we used for the side-nav. Having this grouping strategy
+ * present should ease the transition to RAD V2 by making it the fallback mechanism if tagging has not been implemented.
+ */
+exports.radV1GroupingStrategy = swagger => {
+    const baseUrl = getServerUrlWithDefault(swagger);
+    const groupings = {};
+    Object.keys(swagger.paths).forEach(path => {
+        const topLevelPathGroup = generateTitleFromPath(path);
+        const newPathItems = extractFromPathItem(baseUrl, path, swagger.paths[path], swagger.security);
+        if (groupings[topLevelPathGroup] === undefined) {
+            groupings[topLevelPathGroup] = {
+                title: topLevelPathGroup,
+                operations: newPathItems
+            };
+        }
+        else {
+            groupings[topLevelPathGroup].operations.push(...newPathItems);
+        }
+    });
+    return {
+        groups: Object.keys(groupings).map(pg => groupings[pg])
+    };
+};
+exports.urlGroupingStrategy = swagger => {
+    if (!Object.keys(swagger.paths).some(path => pathItemHasSummary(swagger.paths[path]))) {
+        return exports.radV1GroupingStrategy(swagger);
+    }
+    const paths = Object.keys(swagger.paths).sort();
+    const baseUrl = getServerUrlWithDefault(swagger);
+    const groups = paths.map(path => {
+        const pathItem = swagger.paths[path];
+        return {
+            title: pathItem.summary || generateTitleFromPath(path),
+            description: pathItem.description,
+            operations: extractFromPathItem(baseUrl, path, pathItem, swagger.security)
+        };
+    });
+    return { groups };
+};
+exports.tagGroupingStrategy = swagger => {
+    if (!swagger.tags) {
+        // Fall-back to a urlGrouping strategy if tagging does not work.
+        return exports.urlGroupingStrategy(swagger);
+    }
+    return tagGroupsToOperationGroupings(toTagGroups(swagger.tags, toPathAndOperation(getServerUrlWithDefault(swagger), swagger.paths, swagger.security)));
+};