@stoplight/elements-core 9.0.11 → 9.0.12-beta-0.1

package/src/components/RequestSamples/__tests__/convertRequestToSample.spec.ts

@@ -0,0 +1,118 @@
+import { convertRequestToSample } from '../convertRequestToSample';
+import { requestSampleConfigs } from '../requestSampleConfigs';
+
+const har = {
+  method: 'PUT',
+  url: 'https://todos.stoplight.io/todos/todoId',
+  httpVersion: 'HTTP/1.1',
+  cookies: [],
+  headers: [
+    {
+      name: 'Content-Type',
+      value: 'application/json',
+    },
+    {
+      name: 'account-id',
+      value: 'account-id-default',
+    },
+    {
+      name: 'message-id',
+      value: 'example value',
+    },
+    {
+      name: 'optional_header',
+      value: '',
+    },
+    {
+      name: 'quote',
+      value: '',
+    },
+  ],
+  queryString: [
+    {
+      name: 'value',
+      value: '1',
+    },
+    {
+      name: 'type',
+      value: 'something',
+    },
+    {
+      name: 'API Key',
+      value: '',
+    },
+  ],
+  postData: {
+    mimeType: 'application/json',
+    text: '{\n  "name": "Docs Module",\n  "completed": false\n}',
+    jsonObj: {
+      name: 'Docs Module',
+      completed: false,
+    },
+  },
+  headersSize: -1,
+  bodySize: -1,
+};
+
+const languages = Object.values(requestSampleConfigs).flatMap<string>(({ httpSnippetLanguage, libraries }) => {
+  if (!libraries) {
+    return httpSnippetLanguage;
+  }
+
+  return Object.values(libraries).map(({ httpSnippetLibrary }) => `${httpSnippetLanguage} / ${httpSnippetLibrary}`);
+});
+
+test.each(languages)('given %s, convertRequestToSample converts a request to a sample', async input => {
+  const [language, library] = input.split(' / ');
+
+  expect(convertRequestToSample(language, library, har)).resolves.toMatchSnapshot();
+});
+
+describe('curly bracket encoding', () => {
+  const harWithCurlyBracketsInQuery = {
+    method: 'GET',
+    url: 'https://api.example.com/todos/{todoId}',
+    httpVersion: 'HTTP/1.1',
+    cookies: [],
+    headers: [],
+    queryString: [
+      {
+        name: 'categories',
+        value: '["Information","Status","System","Flow","Content"]',
+      },
+      {
+        name: 'nested',
+        value: '{"key":"value","number":123}',
+      },
+    ],
+    postData: undefined,
+    headersSize: -1,
+    bodySize: -1,
+  };
+
+  it('should preserve curly brackets in query parameters but decode them in path parameters', async () => {
+    const result = await convertRequestToSample('shell', 'curl', harWithCurlyBracketsInQuery);
+
+    expect(result).toContain('/todos/{todoId}'); // Path parameters should be decoded to show placeholders
+    expect(result).toContain('%7B'); // Query parameters should remain encoded
+    expect(result).toContain('%7D'); // Query parameters should remain encoded
+  });
+
+  it('should handle mixed curly brackets in path and query correctly', async () => {
+    const harMixed = {
+      ...harWithCurlyBracketsInQuery,
+      url: 'https://api.example.com/search/{docId}',
+      queryString: [
+        {
+          name: 'filter',
+          value: '{"categories":["Information","Status"],"active":true}',
+        },
+      ],
+    };
+
+    const result = await convertRequestToSample('shell', 'curl', harMixed);
+
+    expect(result).toContain('/search/{docId}'); // Path parameter should show placeholder
+    expect(result).toContain('%7B%22categories%22'); // Query parameter curly brackets should be encoded
+  });
+});

package/src/components/RequestSamples/convertRequestToSample.ts

@@ -0,0 +1,56 @@
+import { Request as HarFormatRequest } from 'har-format';
+import { HTTPSnippet, isValidTargetId } from 'httpsnippet-lite';
+
+export const convertRequestToSample = async (
+  language: string,
+
+  library: string | undefined,
+
+  request: HarFormatRequest,
+) => {
+  if (!isValidTargetId(language)) return null;
+
+  try {
+    const snippet = new HTTPSnippet(request);
+    let converted = await snippet.convert(language, library);
+
+    if (Array.isArray(converted)) {
+      converted = converted[0];
+    } else {
+      converted = converted || null;
+    }
+
+    if (typeof converted === 'string') {
+      // Only decode curly brackets in URL path portion (before ?)
+      // This preserves placeholder parameters like {docId} in paths while keeping
+      // query parameters properly encoded
+      const urlRegex = /(https?:\/\/[^\s'"]+)/g;
+
+      converted = converted.replace(urlRegex, url => {
+        const [pathPart, queryPart] = url.split('?', 2);
+
+        // Decode only curly brackets in the path part
+        const decodedPath = pathPart.replace(/%7B/g, '{').replace(/%7D/g, '}');
+
+        // Keep the query part (if any) as-is
+        return queryPart ? `${decodedPath}?${queryPart}` : decodedPath;
+      });
+
+      if (language === 'shell' && library === 'curl') {
+        // Check if Content-Type is application/x-www-form-urlencoded
+        const isUrlEncoded = request?.headers?.some(
+          header =>
+            header.name.toLowerCase() === 'content-type' && header.value === 'application/x-www-form-urlencoded',
+        ); // Replace --data with --data-urlencode if necessary
+        if (isUrlEncoded) {
+          converted = converted.replace(/--data\b/g, '--data-urlencode');
+        }
+      }
+    }
+    return converted;
+  } catch (err) {
+    console.error(err);
+
+    return null;
+  }
+};

package/src/components/RequestSamples/extractCodeSamples.ts

@@ -0,0 +1,50 @@
+import { isPlainObject } from '@stoplight/json';
+import { isString } from 'lodash';
+
+// Based on Redocly
+// https://redocly.com/docs/api-reference-docs/specification-extensions/x-code-samples/
+
+export type CodeSample = {
+  /**
+   * Code sample language.
+   */
+  lang: string;
+  /**
+   * Code sample library, optional.
+   */
+  lib?: string;
+  /**
+   * Code sample label, for example Node or Python2.7, optional, lib or lang is used by default
+   */
+  label: string;
+  /**
+   * Code sample source code
+   */
+  source: string;
+};
+
+export const extractCodeSamples = (obj: unknown): CodeSample[] => {
+  if (!isPlainObject(obj) || !isPlainObject(obj.extensions)) {
+    return [];
+  }
+
+  const codeSamples = obj.extensions['x-codeSamples'];
+  if (!Array.isArray(codeSamples)) {
+    return [];
+  }
+
+  return codeSamples.reduce((extracted, item) => {
+    if (isPlainObject(item) && isString(item['lang']) && isString(item['source'])) {
+      const lib = isString(item['lib']) ? item['lib'] : undefined;
+      const label = isString(item['label']) ? item['label'] : lib ?? item['lang'];
+      extracted.push({
+        lang: item['lang'],
+        lib,
+        label,
+        source: item['source'], // TODO: does not support $ref objects
+      });
+    }
+
+    return extracted;
+  }, []);
+};

package/src/components/RequestSamples/index.ts

@@ -0,0 +1,2 @@
+export * from './extractCodeSamples';
+export * from './RequestSamples';

package/src/components/RequestSamples/requestSampleConfigs.ts

@@ -0,0 +1,182 @@
+import { CodeViewerLanguage } from '@stoplight/mosaic-code-viewer';
+import { Dictionary } from '@stoplight/types';
+
+export type SupportedLanguage = string;
+export type SupportedLibrary = string;
+export interface LibraryConfig {
+  httpSnippetLibrary: string;
+}
+export interface LanguageConfig {
+  mosaicCodeViewerLanguage: CodeViewerLanguage;
+  httpSnippetLanguage: string;
+  libraries?: Dictionary<LibraryConfig, SupportedLibrary>;
+}
+export type RequestSampleConfigs = Dictionary<LanguageConfig, SupportedLanguage>;
+
+export const requestSampleConfigs: RequestSampleConfigs = {
+  Shell: {
+    mosaicCodeViewerLanguage: 'bash',
+    httpSnippetLanguage: 'shell',
+    libraries: {
+      cURL: {
+        httpSnippetLibrary: 'curl',
+      },
+      HTTPie: {
+        httpSnippetLibrary: 'httpie',
+      },
+      Wget: {
+        httpSnippetLibrary: 'wget',
+      },
+    },
+  },
+  JavaScript: {
+    mosaicCodeViewerLanguage: 'javascript',
+    httpSnippetLanguage: 'javascript',
+    libraries: {
+      Fetch: {
+        httpSnippetLibrary: 'fetch',
+      },
+      XMLHttpRequest: {
+        httpSnippetLibrary: 'xhr',
+      },
+      jQuery: {
+        httpSnippetLibrary: 'jquery',
+      },
+      Axios: {
+        httpSnippetLibrary: 'axios',
+      },
+    },
+  },
+  Node: {
+    mosaicCodeViewerLanguage: 'javascript',
+    httpSnippetLanguage: 'node',
+    libraries: {
+      Native: {
+        httpSnippetLibrary: 'native',
+      },
+      Request: {
+        httpSnippetLibrary: 'request',
+      },
+      Unirest: {
+        httpSnippetLibrary: 'unirest',
+      },
+      Fetch: {
+        httpSnippetLibrary: 'fetch',
+      },
+      Axios: {
+        httpSnippetLibrary: 'axios',
+      },
+    },
+  },
+  Python: {
+    mosaicCodeViewerLanguage: 'python',
+    httpSnippetLanguage: 'python',
+    libraries: {
+      'Python 3': {
+        httpSnippetLibrary: 'python3',
+      },
+      Requests: {
+        httpSnippetLibrary: 'requests',
+      },
+    },
+  },
+  Go: {
+    mosaicCodeViewerLanguage: 'go',
+    httpSnippetLanguage: 'go',
+  },
+  C: {
+    mosaicCodeViewerLanguage: 'c',
+    httpSnippetLanguage: 'c',
+  },
+  'Obj-C': {
+    mosaicCodeViewerLanguage: 'objectivec',
+    httpSnippetLanguage: 'objc',
+  },
+  OCaml: {
+    mosaicCodeViewerLanguage: 'ocaml',
+    httpSnippetLanguage: 'ocaml',
+  },
+  'C#': {
+    mosaicCodeViewerLanguage: 'csharp',
+    httpSnippetLanguage: 'csharp',
+    libraries: {
+      HttpClient: {
+        httpSnippetLibrary: 'httpclient',
+      },
+      RestSharp: {
+        httpSnippetLibrary: 'restsharp',
+      },
+    },
+  },
+  Java: {
+    mosaicCodeViewerLanguage: 'java',
+    httpSnippetLanguage: 'java',
+    libraries: {
+      AsyncHttp: {
+        httpSnippetLibrary: 'asynchttp',
+      },
+      NetHttp: {
+        httpSnippetLibrary: 'nethttp',
+      },
+      OkHttp: {
+        httpSnippetLibrary: 'okhttp',
+      },
+      Unirest: {
+        httpSnippetLibrary: 'unirest',
+      },
+    },
+  },
+  Http: {
+    mosaicCodeViewerLanguage: 'http',
+    httpSnippetLanguage: 'http',
+    libraries: {
+      'Http1.1': {
+        httpSnippetLibrary: 'http1.1',
+      },
+    },
+  },
+  Clojure: {
+    mosaicCodeViewerLanguage: 'clojure',
+    httpSnippetLanguage: 'clojure',
+  },
+  Kotlin: {
+    mosaicCodeViewerLanguage: 'kotlin',
+    httpSnippetLanguage: 'kotlin',
+  },
+  PHP: {
+    mosaicCodeViewerLanguage: 'php',
+    httpSnippetLanguage: 'php',
+    libraries: {
+      cURL: {
+        httpSnippetLibrary: 'curl',
+      },
+      guzzle: {
+        httpSnippetLibrary: 'guzzle',
+      },
+    },
+  },
+  Powershell: {
+    mosaicCodeViewerLanguage: 'powershell',
+    httpSnippetLanguage: 'powershell',
+    libraries: {
+      WebRequest: {
+        httpSnippetLibrary: 'webrequest',
+      },
+      RestMethod: {
+        httpSnippetLibrary: 'restmethod',
+      },
+    },
+  },
+  R: {
+    mosaicCodeViewerLanguage: 'r',
+    httpSnippetLanguage: 'r',
+  },
+  Ruby: {
+    mosaicCodeViewerLanguage: 'ruby',
+    httpSnippetLanguage: 'ruby',
+  },
+  Swift: {
+    mosaicCodeViewerLanguage: 'swift',
+    httpSnippetLanguage: 'swift',
+  },
+};

package/src/components/ResponseExamples/ResponseExamples.spec.tsx

@@ -0,0 +1,121 @@
+import '@testing-library/jest-dom';
+
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import React from 'react';
+
+import { httpOperation as bigExampleOperation } from '../../__fixtures__/operations/big-response';
+import { httpOperation } from '../../__fixtures__/operations/operation-with-examples';
+import { withMosaicProvider } from '../../hoc/withMosaicProvider';
+import * as exampleGenerationUtils from '../../utils/exampleGeneration/exampleGeneration';
+import { chooseOption } from '../../utils/tests/chooseOption';
+import { ResponseExamples as RawResponseExamples } from './ResponseExamples';
+
+const ResponseExamples = withMosaicProvider(RawResponseExamples);
+
+const generatedExample = '{\n"iamtoobig": "string",\n"name": "string",\n"id": "number",\n"email": "string", \n}';
+
+describe('Response Examples', () => {
+  it('displays first provided example by default', () => {
+    const { container } = render(
+      <ResponseExamples httpOperation={httpOperation} responseMediaType="application/json" responseStatusCode="200" />,
+    );
+
+    expect(container).toHaveTextContent('some');
+    expect(container).toHaveTextContent('example');
+  });
+
+  it('allows to choose second example with select', () => {
+    const { container } = render(
+      <ResponseExamples httpOperation={httpOperation} responseMediaType="application/json" responseStatusCode="200" />,
+    );
+
+    chooseOption(screen.getByText('Response Example: First Example'), 'Second Example');
+
+    expect(container).toHaveTextContent('another');
+    expect(container).toHaveTextContent('example');
+  });
+
+  it('generates example based on schema if necessary', () => {
+    const { container } = render(
+      <ResponseExamples httpOperation={httpOperation} responseMediaType="application/json" responseStatusCode="201" />,
+    );
+
+    expect(container).toHaveTextContent('someParameter');
+    expect(container).toHaveTextContent('string');
+  });
+
+  it('does not generate examples for media types other than application/json', () => {
+    const { container } = render(
+      <ResponseExamples httpOperation={httpOperation} responseMediaType="application/xml" responseStatusCode="203" />,
+    );
+
+    expect(container.children[0].children[0]).toBeEmptyDOMElement();
+  });
+
+  it('does not show component if there are no examples and no schemas', () => {
+    const { container } = render(
+      <ResponseExamples httpOperation={httpOperation} responseMediaType="application/json" responseStatusCode="404" />,
+    );
+
+    expect(container.children[0].children[0]).toBeEmptyDOMElement();
+  });
+
+  it('does not show select if there is only one example present', () => {
+    render(
+      <ResponseExamples httpOperation={httpOperation} responseMediaType="application/json" responseStatusCode="202" />,
+    );
+
+    const select = screen.queryByRole('combobox');
+
+    expect(select).not.toBeInTheDocument();
+  });
+
+  it('does not show write only parameters in the response example', () => {
+    const { container } = render(
+      <ResponseExamples httpOperation={httpOperation} responseMediaType="application/json" responseStatusCode="204" />,
+    );
+
+    expect(container).not.toHaveTextContent('writeOnlyParamter');
+    expect(container).toHaveTextContent('someOtherParameter');
+  });
+
+  it('does not show examples >500 lines by default', async () => {
+    jest.spyOn(exampleGenerationUtils, 'exceedsSize').mockImplementation((example: string, size: number = 2) => {
+      return example.split(/\r\n|\r|\n/).length > size;
+    });
+    jest.spyOn(exampleGenerationUtils, 'generateExampleFromMediaTypeContent').mockReturnValue(generatedExample);
+
+    render(
+      <ResponseExamples
+        httpOperation={bigExampleOperation}
+        responseMediaType="application/json"
+        responseStatusCode="200"
+      />,
+    );
+
+    screen.getByText('Large examples are not rendered by default.');
+    jest.restoreAllMocks();
+  });
+
+  it('shows examples >500 lines after clicking "Load Examples" button', async () => {
+    jest.spyOn(exampleGenerationUtils, 'exceedsSize').mockImplementation((example: string, size: number = 2) => {
+      return example.split(/\r\n|\r|\n/).length > size;
+    });
+    jest.spyOn(exampleGenerationUtils, 'generateExampleFromMediaTypeContent').mockReturnValue(generatedExample);
+
+    render(
+      <ResponseExamples
+        httpOperation={bigExampleOperation}
+        responseMediaType="application/json"
+        responseStatusCode="200"
+      />,
+    );
+
+    const button = screen.getByRole('button', { name: 'load-example' });
+    userEvent.click(button);
+
+    expect(await screen.findByText('"iamtoobig"')).toBeInTheDocument();
+    jest.restoreAllMocks();
+  });
+});

package/src/components/ResponseExamples/ResponseExamples.stories.tsx

@@ -0,0 +1,21 @@
+import { Meta, Story } from '@storybook/react';
+import * as React from 'react';
+
+import { httpOperation } from '../../__fixtures__/operations/operation-with-examples';
+import { ResponseExamples, ResponseExamplesProps } from './ResponseExamples';
+
+export default {
+  title: 'Internal/ResponseExamples',
+  component: ResponseExamples,
+} as Meta<ResponseExamplesProps>;
+
+const Template: Story<ResponseExamplesProps> = args => <ResponseExamples {...args} />;
+
+export const HoistedStory = Template.bind({});
+
+HoistedStory.args = {
+  httpOperation,
+  responseStatusCode: '200',
+  responseMediaType: 'application/json',
+};
+HoistedStory.storyName = 'ResponseExamples';

package/src/components/ResponseExamples/ResponseExamples.tsx

@@ -0,0 +1,79 @@
+import { CopyButton, Panel, Select, Text } from '@stoplight/mosaic';
+import { CodeViewer } from '@stoplight/mosaic-code-viewer';
+import { IHttpEndpointOperation, IMediaTypeContent } from '@stoplight/types';
+import * as React from 'react';
+
+import { exceedsSize, useGenerateExampleFromMediaTypeContent } from '../../utils/exampleGeneration/exampleGeneration';
+import { LoadMore } from '../LoadMore';
+
+export interface ResponseExamplesProps {
+  httpOperation: IHttpEndpointOperation;
+  responseStatusCode?: string;
+  responseMediaType?: string;
+}
+
+export const ResponseExamples = ({ httpOperation, responseMediaType, responseStatusCode }: ResponseExamplesProps) => {
+  const [chosenExampleIndex, setChosenExampleIndex] = React.useState(0);
+  const [show, setShow] = React.useState<boolean>(false);
+  const [loading, setLoading] = React.useState<boolean>(false);
+
+  const response = httpOperation.responses.find(response => response.code === responseStatusCode);
+  const responseContents = response?.contents?.find(content => content.mediaType === responseMediaType);
+  let userDefinedExamples: IMediaTypeContent['examples'];
+  if (responseContents?.examples && responseContents?.examples.length > 0) {
+    userDefinedExamples = responseContents?.examples;
+  }
+
+  const responseExample = useGenerateExampleFromMediaTypeContent(responseContents, chosenExampleIndex, {
+    skipWriteOnly: true,
+  });
+
+  const handleLoadMore = () => {
+    setLoading(true);
+    setTimeout(() => setShow(true), 50);
+  };
+
+  if (!userDefinedExamples && responseMediaType !== 'application/json') return null;
+
+  if (!responseExample) return null;
+
+  const examplesSelect = userDefinedExamples && userDefinedExamples.length > 1 && (
+    <Select
+      aria-label="Response Example"
+      value={String(chosenExampleIndex)}
+      options={userDefinedExamples.map((example, index) => ({ value: index, label: example.key }))}
+      onChange={value => setChosenExampleIndex(parseInt(String(value), 10))}
+      size="sm"
+      triggerTextPrefix="Response Example: "
+    />
+  );
+
+  return (
+    <Panel rounded isCollapsible={false}>
+      <Panel.Titlebar rightComponent={<CopyButton size="sm" copyValue={responseExample || ''} />}>
+        {examplesSelect || <Text color="body">Response Example</Text>}
+      </Panel.Titlebar>
+      <Panel.Content p={0}>
+        {show || !exceedsSize(responseExample) ? (
+          <CodeViewer
+            aria-label={responseExample}
+            noCopyButton
+            maxHeight="500px"
+            language="json"
+            value={responseExample}
+            showLineNumbers
+            style={
+              // when not rendering in prose (markdown), reduce font size to be consistent with base UI
+              {
+                // @ts-expect-error react css typings do not allow for css variables...
+                '--fs-code': 12,
+              }
+            }
+          />
+        ) : (
+          <LoadMore loading={loading} onClick={handleLoadMore} />
+        )}
+      </Panel.Content>
+    </Panel>
+  );
+};