@stoplight/elements 9.0.11 → 9.0.12-beta-0.2

package/src/utils/oas/__tests__/oas.spec.ts

@@ -0,0 +1,411 @@
+import { transformOasToServiceNode } from '../';
+
+const oas3Document = {
+  'x-stoplight': { id: 'abc' },
+  openapi: '3.0.0',
+  info: {
+    title: 'oas3',
+    version: '1.0.0',
+  },
+  tags: [{ name: 'operation-tag' }, { name: 'model-tag' }],
+  paths: {
+    '/todos': {
+      get: {
+        summary: 'Get Todos',
+        tags: ['operation-tag'],
+      },
+    },
+  },
+  components: {
+    schemas: {
+      Todo: {
+        type: 'object',
+        properties: {
+          id: {
+            type: 'integer',
+          },
+        },
+        title: 'Todo',
+        'x-tags': ['model-tag'],
+      },
+    },
+  },
+};
+
+const oas2Document = {
+  'x-stoplight': { id: 'abc' },
+  swagger: '2.0.0',
+  info: {
+    title: 'oas2',
+    version: '1.0.0',
+  },
+  tags: [{ name: 'operation-tag' }, { name: 'model-tag' }],
+  paths: {
+    '/todos': {
+      get: {
+        summary: 'Get Todos',
+        tags: ['operation-tag'],
+      },
+    },
+  },
+  definitions: {
+    Todo: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'integer',
+        },
+      },
+      title: 'Todo',
+      'x-tags': ['model-tag'],
+    },
+  },
+};
+
+describe('computeOasNodes', () => {
+  it('should return null for invalid document', () => {
+    expect(transformOasToServiceNode({})).toBeNull();
+  });
+
+  it('should return oas nodes for oas3 document', () => {
+    expect(transformOasToServiceNode(oas3Document)).toStrictEqual({
+      type: 'http_service',
+      uri: '/',
+      name: 'oas3',
+      data: {
+        id: 'abc',
+        version: '1.0.0',
+        name: 'oas3',
+        tags: [
+          {
+            id: '68c460dd9e97a',
+            name: 'operation-tag',
+          },
+          {
+            id: 'feec8b579ae6b',
+            name: 'model-tag',
+          },
+        ],
+        extensions: {
+          'x-stoplight': {
+            id: 'abc',
+          },
+        },
+        infoExtensions: {},
+      },
+      tags: ['operation-tag', 'model-tag'],
+      children: [
+        {
+          type: 'http_operation',
+          uri: '/paths/todos/get',
+          data: {
+            id: 'c35bc6b301d97',
+            method: 'get',
+            path: '/todos',
+            summary: 'Get Todos',
+            responses: [],
+            servers: [],
+            request: {
+              headers: [],
+              query: [],
+              cookie: [],
+              path: [],
+            },
+            tags: [
+              {
+                id: '68c460dd9e97a',
+                name: 'operation-tag',
+              },
+            ],
+            security: [],
+            securityDeclarationType: 'inheritedFromService',
+            extensions: {},
+          },
+          name: 'Get Todos',
+          tags: ['operation-tag'],
+        },
+        {
+          type: 'model',
+          uri: '/schemas/Todo',
+          data: {
+            type: 'object',
+            properties: {
+              id: {
+                type: 'integer',
+              },
+            },
+            title: 'Todo',
+            'x-tags': ['model-tag'],
+          },
+          name: 'Todo',
+          tags: ['model-tag'],
+        },
+      ],
+    });
+  });
+
+  it('should return oas nodes for oas2 document', () => {
+    expect(transformOasToServiceNode(oas2Document)).toStrictEqual({
+      type: 'http_service',
+      uri: '/',
+      name: 'oas2',
+      data: {
+        id: 'abc',
+        name: 'oas2',
+        tags: [
+          {
+            id: '68c460dd9e97a',
+            name: 'operation-tag',
+          },
+          {
+            id: 'feec8b579ae6b',
+            name: 'model-tag',
+          },
+        ],
+        extensions: {
+          'x-stoplight': {
+            id: 'abc',
+          },
+        },
+        infoExtensions: {},
+        version: '1.0.0',
+      },
+      tags: ['operation-tag', 'model-tag'],
+      children: [
+        {
+          type: 'http_operation',
+          uri: '/paths/todos/get',
+          data: {
+            id: 'c35bc6b301d97',
+            method: 'get',
+            path: '/todos',
+            summary: 'Get Todos',
+            responses: [],
+            servers: [],
+            request: {
+              cookie: [],
+              headers: [],
+              path: [],
+              query: [],
+            },
+            tags: [
+              {
+                id: '68c460dd9e97a',
+                name: 'operation-tag',
+              },
+            ],
+            security: [],
+            securityDeclarationType: 'inheritedFromService',
+            extensions: {},
+          },
+          name: 'Get Todos',
+          tags: ['operation-tag'],
+        },
+        {
+          type: 'model',
+          uri: '/schemas/Todo',
+          data: {
+            type: 'object',
+            properties: {
+              id: {
+                type: 'integer',
+              },
+            },
+            title: 'Todo',
+            'x-tags': ['model-tag'],
+          },
+          name: 'Todo',
+          tags: ['model-tag'],
+        },
+      ],
+    });
+  });
+
+  it('should fallback to operationId', () => {
+    expect(
+      transformOasToServiceNode({
+        'x-stoplight': { id: 'def' },
+        openapi: '3.0.0',
+        info: {
+          title: 'oas3',
+          version: '1.0.0',
+        },
+        paths: {
+          '/todos': {
+            get: {
+              operationId: 'get-todos',
+            },
+          },
+        },
+      }),
+    ).toEqual({
+      type: 'http_service',
+      uri: '/',
+      name: 'oas3',
+      tags: [],
+      data: {
+        id: 'def',
+        version: '1.0.0',
+        name: 'oas3',
+        extensions: {
+          'x-stoplight': {
+            id: 'def',
+          },
+        },
+        infoExtensions: {},
+      },
+      children: [
+        {
+          type: 'http_operation',
+          uri: '/operations/get-todos',
+          data: {
+            id: 'a61f53c324669',
+            iid: 'get-todos',
+            method: 'get',
+            path: '/todos',
+            responses: [],
+            servers: [],
+            request: {
+              headers: [],
+              query: [],
+              cookie: [],
+              path: [],
+            },
+            tags: [],
+            security: [],
+            securityDeclarationType: 'inheritedFromService',
+            extensions: {},
+          },
+          tags: [],
+          name: 'get-todos',
+        },
+      ],
+    });
+  });
+
+  it('should not throw error for non-common url paths', () => {
+    expect(
+      transformOasToServiceNode({
+        'x-stoplight': { id: 'def' },
+        openapi: '3.0.0',
+        info: {
+          title: 'oas3',
+          version: '1.0.0',
+        },
+        paths: {
+          '/todos/{id}/flow)': {
+            get: {
+              operationId: 'get-todos',
+            },
+          },
+        },
+      }),
+    ).toEqual({
+      type: 'http_service',
+      uri: '/',
+      name: 'oas3',
+      tags: [],
+      data: {
+        id: 'def',
+        version: '1.0.0',
+        name: 'oas3',
+        extensions: {
+          'x-stoplight': {
+            id: 'def',
+          },
+        },
+        infoExtensions: {},
+      },
+      children: [
+        {
+          type: 'http_operation',
+          uri: '/operations/get-todos',
+          data: {
+            id: '7b7e36ffa6501',
+            iid: 'get-todos',
+            method: 'get',
+            path: '/todos/{id}/flow)',
+            responses: [],
+            servers: [],
+            request: {
+              headers: [],
+              query: [],
+              cookie: [],
+              path: [],
+            },
+            tags: [],
+
+            securityDeclarationType: 'inheritedFromService',
+            security: [],
+            extensions: {},
+          },
+          tags: [],
+          name: 'get-todos',
+        },
+      ],
+    });
+  });
+
+  it('should filter out unused security nodes and not show duplicate nodes', () => {
+    const serviceNode = transformOasToServiceNode({
+      openapi: '3.1.0',
+      'x-stoplight': {
+        id: 'nso1sfqvio7bp',
+      },
+      info: {
+        title: 'Test',
+        version: '1.0',
+      },
+      servers: [
+        {
+          url: 'http://localhost:3000',
+        },
+      ],
+      paths: {
+        '/users': {
+          get: {
+            summary: 'Your GET endpoint',
+            tags: [],
+            responses: {},
+            operationId: 'get-users',
+            'x-stoplight': {
+              id: 'oblhqa66gbqqg',
+            },
+            security: [
+              {
+                API_Key_Query: [],
+              },
+            ],
+          },
+        },
+      },
+      components: {
+        schemas: {},
+        securitySchemes: {
+          API_Key_Query: {
+            name: 'API Key',
+            type: 'apiKey',
+            in: 'query',
+          },
+          API_Key_Header: {
+            name: 'API Key',
+            type: 'apiKey',
+            in: 'header',
+          },
+          API_Key_Cookie: {
+            name: 'API Key',
+            type: 'apiKey',
+            in: 'cookie',
+          },
+        },
+      },
+      security: [
+        {
+          API_Key_Query: [],
+        },
+      ],
+    });
+
+    expect(serviceNode?.data.security).toHaveLength(1);
+  });
+});

package/src/utils/oas/index.ts

@@ -0,0 +1,192 @@
+import { slugify } from '@stoplight/elements-core';
+import {
+  Oas2HttpOperationTransformer,
+  Oas2HttpServiceTransformer,
+  Oas3HttpEndpointOperationTransformer,
+  Oas3HttpServiceTransformer,
+  OPERATION_CONFIG,
+  WEBHOOK_CONFIG,
+} from '@stoplight/http-spec/oas';
+import { transformOas2Operation, transformOas2Service } from '@stoplight/http-spec/oas2';
+import { transformOas3Operation, transformOas3Service } from '@stoplight/http-spec/oas3';
+import { encodePointerFragment, pointerToPath } from '@stoplight/json';
+import { IHttpOperation, IHttpWebhookOperation, NodeType } from '@stoplight/types';
+import { get, isObject, last } from 'lodash';
+import { OpenAPIObject as _OpenAPIObject, PathObject } from 'openapi3-ts';
+import { Spec } from 'swagger-schema-official';
+
+import { oas2SourceMap } from './oas2';
+import { oas3SourceMap } from './oas3';
+import { ISourceNodeMap, NodeTypes, ServiceChildNode, ServiceNode } from './types';
+
+type OpenAPIObject = _OpenAPIObject & {
+  webhooks?: PathObject;
+};
+
+type SpecDocument = Spec | OpenAPIObject;
+
+const isOas2 = (parsed: unknown): parsed is Spec =>
+  isObject(parsed) &&
+  'swagger' in parsed &&
+  Number.parseInt(String((parsed as Partial<{ swagger: unknown }>).swagger)) === 2;
+
+const isOas3 = (parsed: unknown): parsed is OpenAPIObject =>
+  isObject(parsed) &&
+  'openapi' in parsed &&
+  Number.parseFloat(String((parsed as Partial<{ openapi: unknown }>).openapi)) >= 3;
+
+const isOas31 = (parsed: unknown): parsed is OpenAPIObject =>
+  isObject(parsed) &&
+  'openapi' in parsed &&
+  Number.parseFloat(String((parsed as Partial<{ openapi: unknown }>).openapi)) === 3.1;
+
+const OAS_MODEL_REGEXP = /((definitions|components)\/?(schemas)?)\//;
+
+export function transformOasToServiceNode(apiDescriptionDocument: unknown) {
+  if (isOas31(apiDescriptionDocument)) {
+    return computeServiceNode(
+      { ...apiDescriptionDocument, jsonSchemaDialect: 'http://json-schema.org/draft-07/schema#' },
+      oas3SourceMap,
+      transformOas3Service,
+      transformOas3Operation,
+    );
+  }
+  if (isOas3(apiDescriptionDocument)) {
+    return computeServiceNode(apiDescriptionDocument, oas3SourceMap, transformOas3Service, transformOas3Operation);
+  } else if (isOas2(apiDescriptionDocument)) {
+    return computeServiceNode(apiDescriptionDocument, oas2SourceMap, transformOas2Service, transformOas2Operation);
+  }
+
+  return null;
+}
+
+function computeServiceNode(
+  document: SpecDocument,
+  map: ISourceNodeMap[],
+  transformService: Oas2HttpServiceTransformer | Oas3HttpServiceTransformer,
+  transformOperation: Oas2HttpOperationTransformer | Oas3HttpEndpointOperationTransformer,
+) {
+  const serviceDocument = transformService({ document });
+  const serviceNode: ServiceNode = {
+    type: NodeType.HttpService,
+    uri: '/',
+    name: serviceDocument.name,
+    data: serviceDocument,
+    tags: serviceDocument.tags?.map(tag => tag.name) || [],
+    children: computeChildNodes(document, document, map, transformOperation),
+  };
+
+  return serviceNode;
+}
+
+function computeChildNodes(
+  document: SpecDocument,
+  data: SpecDocument,
+  map: ISourceNodeMap[],
+  transformer: Oas2HttpOperationTransformer | Oas3HttpEndpointOperationTransformer,
+  parentUri: string = '',
+) {
+  const nodes: ServiceChildNode[] = [];
+
+  if (!isObject(data)) return nodes;
+
+  for (const [key, value] of Object.entries(data)) {
+    const sanitizedKey = encodePointerFragment(key);
+    const match = findMapMatch(sanitizedKey, map);
+
+    if (match) {
+      const uri = `${parentUri}/${sanitizedKey}`;
+      const jsonPath = pointerToPath(`#${uri}`);
+
+      if (match.type === NodeTypes.Operation && jsonPath.length === 3) {
+        const path = String(jsonPath[1]);
+        const method = String(jsonPath[2]);
+        const operationDocument = transformer({
+          document,
+          name: path,
+          method,
+          config: OPERATION_CONFIG,
+        }) as IHttpOperation;
+        let parsedUri;
+        const encodedPath = String(encodePointerFragment(path));
+
+        if (operationDocument.iid) {
+          parsedUri = `/operations/${operationDocument.iid}`;
+        } else {
+          parsedUri = uri.replace(encodedPath, slugify(path));
+        }
+
+        nodes.push({
+          type: NodeType.HttpOperation,
+          uri: parsedUri,
+          data: operationDocument,
+          name: operationDocument.summary || operationDocument.iid || operationDocument.path,
+          tags: operationDocument.tags?.map(tag => tag.name) || [],
+        });
+      } else if (match.type === NodeTypes.Webhook && jsonPath.length === 3) {
+        const name = String(jsonPath[1]);
+        const method = String(jsonPath[2]);
+        const webhookDocument = transformer({
+          document,
+          name,
+          method,
+          config: WEBHOOK_CONFIG,
+        }) as IHttpWebhookOperation;
+
+        let parsedUri;
+        const encodedPath = String(encodePointerFragment(name));
+
+        if (webhookDocument.iid) {
+          parsedUri = `/webhooks/${webhookDocument.iid}`;
+        } else {
+          parsedUri = uri.replace(encodedPath, slugify(name));
+        }
+
+        nodes.push({
+          type: NodeType.HttpWebhook,
+          uri: parsedUri,
+          data: webhookDocument,
+          name: webhookDocument.summary || webhookDocument.name,
+          tags: webhookDocument.tags?.map(tag => tag.name) || [],
+        });
+      } else if (match.type === NodeTypes.Model) {
+        const schemaDocument = get(document, jsonPath);
+        const parsedUri = uri.replace(OAS_MODEL_REGEXP, 'schemas/');
+
+        nodes.push({
+          type: NodeType.Model,
+          uri: parsedUri,
+          data: schemaDocument,
+          name: schemaDocument.title || last(uri.split('/')) || '',
+          tags: schemaDocument['x-tags'] || [],
+        });
+      }
+
+      if (match.children) {
+        nodes.push(...computeChildNodes(document, value, match.children, transformer, uri));
+      }
+    }
+  }
+
+  return nodes;
+}
+
+function findMapMatch(key: string | number, map: ISourceNodeMap[]): ISourceNodeMap | void {
+  if (typeof key === 'number') return;
+  for (const entry of map) {
+    const escapedKey = key.replace(/[\\^$*+?.()|[\]{}]/g, '\\$&');
+
+    if (!!entry.match?.match(escapedKey) || (entry.notMatch !== void 0 && !entry.notMatch.match(escapedKey))) {
+      return entry;
+    }
+  }
+}
+
+export function isJson(value: string) {
+  try {
+    JSON.parse(value);
+  } catch (e) {
+    return false;
+  }
+  return true;
+}

package/src/utils/oas/oas2.ts

@@ -0,0 +1,31 @@
+import { ISourceNodeMap, NodeTypes } from './types';
+
+export const oas2SourceMap: ISourceNodeMap[] = [
+  {
+    match: 'paths',
+    type: NodeTypes.Paths,
+    children: [
+      {
+        notMatch: '^x-',
+        type: NodeTypes.Path,
+        children: [
+          {
+            match: 'get|post|put|delete|options|head|patch|trace',
+            type: NodeTypes.Operation,
+          },
+        ],
+      },
+    ],
+  },
+
+  {
+    match: 'definitions',
+    type: NodeTypes.Models,
+    children: [
+      {
+        notMatch: '^x-',
+        type: NodeTypes.Model,
+      },
+    ],
+  },
+];

package/src/utils/oas/oas3.ts

@@ -0,0 +1,54 @@
+import { ISourceNodeMap, NodeTypes } from './types';
+
+export const oas3SourceMap: ISourceNodeMap[] = [
+  {
+    match: 'paths',
+    type: NodeTypes.Paths,
+    children: [
+      {
+        notMatch: '^x-',
+        type: NodeTypes.Path,
+        children: [
+          {
+            match: 'get|post|put|delete|options|head|patch|trace',
+            type: NodeTypes.Operation,
+          },
+        ],
+      },
+    ],
+  },
+
+  {
+    match: 'webhooks',
+    type: NodeTypes.Webhooks,
+    children: [
+      {
+        notMatch: '^x-',
+        type: NodeTypes.Webhook,
+        children: [
+          {
+            match: 'get|post|put|delete|options|head|patch|trace',
+            type: NodeTypes.Webhook,
+          },
+        ],
+      },
+    ],
+  },
+
+  {
+    match: 'components',
+    type: NodeTypes.Components,
+    children: [
+      {
+        match: 'schemas',
+        type: NodeTypes.Models,
+        children: [
+          {
+            notMatch: '^x-',
+            type: NodeTypes.Model,
+          },
+        ],
+      },
+    ],
+  },
+];