@digi-frontend/dgate-api-documentation 1.0.0 → 1.0.1

package/src/helpers/docs.helper.ts

@@ -0,0 +1,42 @@
+import { ApiSpecModel } from '@entities/index'
+import { HTTPMethod, OpenAPIFile } from '@entities/openApi'
+import { nanoid } from 'nanoid'
+import { OverviewData, TagData } from 'src/layout/docsLayout'
+
+export const transformOpenApiToDocs = (api: ApiSpecModel): OverviewData => {
+  const parsedOpenApi: OpenAPIFile =
+    typeof api.metaData.openApiJson === 'string'
+      ? JSON.parse(api.metaData.openApiJson)
+      : api.metaData.openApiJson
+
+  const groupedPathsByTags: Record<string, TagData[]> = { default: [] }
+  const validTags = new Set(parsedOpenApi?.tags?.map(({ name }) => name) || [])
+
+  for (const [path, methods] of Object.entries(parsedOpenApi.paths)) {
+    for (const [method, methodData] of Object.entries(methods)) {
+      const entry = { ...methodData, method: method as HTTPMethod, path }
+      const resourceTags = methodData.tags ?? []
+
+      const matchedTags = resourceTags.filter((tag) => validTags.has(tag))
+
+      if (matchedTags.length > 0) {
+        matchedTags.forEach((tag) => {
+          if (!groupedPathsByTags[tag]) groupedPathsByTags[tag] = []
+          groupedPathsByTags[tag].push({ ...entry, id: nanoid(8) } as TagData)
+        })
+      } else {
+        groupedPathsByTags.default.push({ ...entry, id: nanoid(8) } as TagData)
+      }
+    }
+  }
+
+  return {
+    ...parsedOpenApi.info,
+    apiSpecId: api.apiSpecId,
+    contextPath: api.contextPath,
+    associatedProduct: api.associatedProduct,
+    apiVersions: api.apiVersions,
+    tags: groupedPathsByTags,
+    servers: parsedOpenApi.servers,
+  }
+}

package/src/helpers/layout.helper.ts

@@ -0,0 +1,187 @@
+import { TransformedPathsArray } from '@entities/layout.type'
+import { OpenAPIFile, SecurityScheme } from '@entities/openApi'
+import { TransformedOpenApi } from '@entities/transformedOpenApi'
+
+export const transformOpenApiObject = (openApiJson: OpenAPIFile): TransformedOpenApi => {
+  if (openApiJson.components && openApiJson.components.securitySchemes) {
+    const authKey = Object.keys(openApiJson.components.securitySchemes)?.at(0)
+    if (authKey) {
+      openApiJson.components.securitySchemes[authKey].type = openApiJson?.components
+        ?.securitySchemes?.[authKey]?.type as SecurityScheme['type']
+    }
+  } else {
+    openApiJson.components = {
+      securitySchemes: {
+        Public: {
+          type: 'http',
+          scheme: 'public',
+        },
+      },
+    }
+  }
+
+  if (!openApiJson.tags) {
+    openApiJson.tags = []
+  }
+
+  return {
+    ...openApiJson,
+    paths: transformPathsToArray(openApiJson.paths),
+  } as TransformedOpenApi
+}
+
+export const transformOpenApiObjectToOrigin = (values: TransformedOpenApi): OpenAPIFile => {
+  const object = {
+    ...values,
+    paths: transformPathsArrayToOrigin(values.paths),
+  }
+  if (object.components && object.components.securitySchemes) {
+    const authKey = Object.keys(object.components.securitySchemes)?.at(0)
+    if (authKey) {
+      if (object.components.securitySchemes[authKey].type.toLowerCase() == 'APIKEY'.toLowerCase()) {
+        object.components.securitySchemes[authKey].in = object.components.securitySchemes[authKey]
+          .in as SecurityScheme['in']
+      }
+      object.components.securitySchemes[authKey].type = object?.components?.securitySchemes?.[
+        authKey
+      ]?.type as SecurityScheme['type']
+    }
+  }
+  return object
+}
+
+export const transformPathsToArray = (paths: OpenAPIFile['paths']): TransformedPathsArray | any => {
+  const transformedPaths = Object.entries(paths).map(([path, methods]) => ({
+    path,
+    methods: Object.entries(methods).map(([method, methodProps]) => {
+      const obj: any = {
+        ...methodProps,
+        type: method,
+        tags: methodProps.tags || [],
+        summary: methodProps.summary || '',
+        responses: Object.entries(methodProps.responses).map(([code, codeProps]) => {
+          const contentType = Object.keys(codeProps.content || {})[0]
+          const headers = !codeProps?.headers ? {} : codeProps.headers
+          return {
+            code,
+            headers,
+            content: {
+              contentType,
+              schema: {
+                ...codeProps.content?.[contentType]?.schema,
+                properties: JSON.stringify(codeProps.content?.[contentType]?.schema?.properties),
+              },
+            },
+          }
+        }),
+      }
+      // Add parameters if it does not exist in the original JSON
+      if (!methodProps?.parameters) {
+        obj.parameters = []
+      }
+
+      // load response headers parameters
+
+      if (method.toLowerCase() != 'get') {
+        const contentType = Object.keys(methodProps?.requestBody?.content || {})[0]
+        const reqSchema = methodProps?.requestBody?.content?.schema
+        const requestBodyData = methodProps?.requestBody?.content?.schema?.properties
+          ? {
+              content: {
+                contentType,
+                schema: {
+                  ...reqSchema,
+                  properties: reqSchema?.properties ? JSON.stringify(reqSchema?.properties) : '{}',
+                },
+              },
+            }
+          : {
+              content: {
+                contentType: 'application/json',
+                schema: {
+                  properties: '{}',
+                  type: 'object',
+                },
+              },
+            }
+
+        obj['requestBody'] = requestBodyData
+      }
+      return obj
+    }),
+  }))
+
+  return transformedPaths
+}
+
+const validateBodyForResponse = (content, method) => {
+  if (!(content?.schema as any) || !(content?.schema as any)?.properties) {
+    return {}
+  }
+  let _content = JSON.parse((content?.schema as any)?.properties as string)
+
+  return _content
+}
+
+export const transformPathsArrayToOrigin = (paths: TransformedPathsArray): OpenAPIFile['paths'] => {
+  return paths.reduce((acc, { path, methods }) => {
+    acc[path] = methods.reduce(
+      (methodAcc, { type, tags, responses, summary, requestBody, ...rest }) => {
+        // Initialize the method object
+        methodAcc[type] = {
+          ...rest,
+          tags,
+          summary,
+          responses: responses.reduce((respAcc, { code, content, headers }) => {
+            const formattedHeaders: Record<string, any> = {}
+            if (headers) {
+              for (const [key, value] of Object.entries(headers)) {
+                formattedHeaders[key] = {
+                  description: value.description || '',
+                  required: value.required || false,
+                  schema: value.schema || {},
+                }
+              }
+            }
+            respAcc[code] = {
+              description: 'Success', // Assuming this is static from the original data
+              content: content.contentType
+                ? {
+                    [content.contentType]: {
+                      schema: {
+                        ...(content.schema as object),
+                        properties: validateBodyForResponse(content, type),
+                      },
+                    },
+                  }
+                : {},
+              headers: formattedHeaders,
+            }
+            return respAcc
+          }, {} as Record<string, any>),
+        }
+
+        const parsedRequestBodyProps =
+          type !== 'get' ? JSON.parse(requestBody.content.schema.properties) : {}
+        // Add requestBody for non-GET methods
+        if (type !== 'get') {
+          methodAcc[type].requestBody = {
+            content: {
+              [requestBody.content.contentType]: {
+                schema: {
+                  ...requestBody.content.schema,
+                  properties: parsedRequestBodyProps,
+                },
+              },
+            },
+          }
+        }
+
+        return methodAcc
+      },
+      {} as Record<string, any>
+    )
+
+    return acc
+  }, {} as OpenAPIFile['paths'])
+}

package/src/helpers/methodAccordion.helper.ts

@@ -0,0 +1,20 @@
+export const handleStatusColor = (code: number): string => {
+  if (code >= 200 && code < 300) {
+    return 'green' // 2xx codes
+  } else if (code >= 400 && code < 500) {
+    return 'red' // 4xx codes
+  } else if (code >= 500 && code < 600) {
+    return 'red' // 5xx codes
+  } else if (code >= 100 && code < 200) {
+    return 'blue' // 1xx codes (Informational)
+  } else if (code >= 300 && code < 400) {
+    return 'orange' // 3xx codes (Redirection)
+  } else {
+    return 'gray' // Default or invalid status codes
+  }
+}
+
+export const  capitalize = (str)=> {
+  if (!str) return "";
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/src/index.ts

@@ -1 +1,2 @@
-export { default as Layout } from './layout/layout'
+export { default as Layout } from './layout/layout'
+export { default as DocsLayout } from './layout/docsLayout'

package/src/layout/docsComponents/Codebox/Codebox.tsx

@@ -0,0 +1,61 @@
+import React, { useState } from 'react'
+import { Light as SyntaxHighlighter } from 'react-syntax-highlighter'
+import json from 'react-syntax-highlighter/dist/esm/languages/hljs/json'
+import * as hljs from 'react-syntax-highlighter/dist/esm/styles/hljs'
+import styles from './style.module.scss'
+import SVGLoader from '../../../components/SVGLoader/SVGLoader'
+import { Copy } from '../../../assets/icons'
+import { copyToClipboard } from '../../../utils'
+
+SyntaxHighlighter.registerLanguage('json', json)
+
+const Codebox = ({ code }: { code: string }) => {
+  const [theme, setTheme] = useState<'LIGHT' | 'DARK'>('DARK')
+
+  return (
+    <div className={styles.codebox}>
+      <div className={styles.codebox_header}>
+        <div
+          role="button"
+          tabIndex={-1}
+          onClick={() => theme !== 'LIGHT' && setTheme('LIGHT')}
+          className={`${styles.codebox_header_themeToggle} ${styles.codebox_header_themeToggle_light}`}
+          title="Light theme"
+        ></div>
+        <div
+          role="button"
+          tabIndex={-1}
+          onClick={() => theme !== 'DARK' && setTheme('DARK')}
+          className={`${styles.codebox_header_themeToggle} ${styles.codebox_header_themeToggle_dark}`}
+          title="Dark theme"
+        ></div>
+        <SVGLoader
+          src={Copy}
+          width="0.75rem"
+          height="0.75rem"
+          className={styles.codebox_header_copyIcon}
+          onClick={() => copyToClipboard(code)}
+        />
+      </div>
+      <SyntaxHighlighter
+        language="json"
+        style={theme === 'LIGHT' ? hljs.stackoverflowLight : hljs.stackoverflowDark}
+        showLineNumbers
+        wrapLines
+        customStyle={{
+          margin: 0,
+          height: '13.75rem',
+          overflowY: 'auto',
+          padding: '0.75rem 1rem 0 1.5rem',
+          backgroundColor: theme === 'DARK' ? '#455162' : '#F7F7F7',
+          fontSize: '0.75rem',
+        }}
+        lineProps={{ className: 'custom-code-line' }}
+      >
+        {code}
+      </SyntaxHighlighter>
+    </div>
+  )
+}
+
+export default Codebox

package/src/layout/docsComponents/Codebox/style.module.scss

@@ -0,0 +1,43 @@
+.codebox {
+  border-radius: 0.25rem;
+  overflow: hidden;
+
+  &_header {
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+    padding-left: 0.5rem;
+    height: 1.75rem;
+    border: 1px solid #bbbec5;
+    border-top-right-radius: 0.25rem;
+    border-top-left-radius: 0.25rem;
+
+    &_themeToggle {
+      width: 0.75rem;
+      min-width: 0.75rem;
+      aspect-ratio: 1 / 1;
+      border: 1px solid transparent;
+      border-radius: 100%;
+      cursor: pointer;
+
+      &_dark {
+        background-color: #455162;
+        border-color: #6b7280;
+      }
+
+      &_light {
+        background-color: #edf1fb;
+        border-color: #6b7280;
+      }
+    }
+
+    &_copyIcon {
+      cursor: pointer;
+    }
+  }
+
+  :global(.custom-code-line),
+  :global(.custom-code-line span) {
+    font-family: 'Cascadia Code', sans-serif;
+  }
+}

package/src/layout/docsComponents/DocsAside/DocsAside.tsx

@@ -0,0 +1,93 @@
+import React, { useState } from 'react'
+import { EndpointData } from 'src/layout/docsLayout'
+import Codebox from '../Codebox/Codebox'
+import { Option, SelectGroup } from 'digitinary-ui'
+import { httpStatusCodes } from '../../../constants/index'
+import { handleStatusColor } from '../../../helpers/methodAccordion.helper'
+import styles from './style.module.scss'
+
+const httpStatusCodeOptions: Option[] = httpStatusCodes.map((code) => ({
+  label: (
+    <div className={styles.statusCodeOptionContainer}>
+      <div
+        className={styles.statusCodeOptionCircle}
+        style={{ backgroundColor: handleStatusColor(code) }}
+      ></div>
+      <span>{code}</span>
+    </div>
+  ),
+  value: String(code),
+}))
+
+const DocsAside = ({ data }: { data: EndpointData }) => {
+  const [selectedResStatusCode, setSelectedResStatusCode] = useState(httpStatusCodeOptions[4])
+  const currentResponse = Object.entries(data.responses)
+    .map(([code, data]) => ({ code, data }))
+    .find((res) => res.code === selectedResStatusCode.value)
+
+  const stringifyRequestBody = () => {
+    if (data?.requestBody?.content) {
+      const contentKey = Object.keys(data?.requestBody?.content)[0]
+      return JSON.stringify(data?.requestBody?.content[contentKey]?.schema?.properties, null, 2)
+    } else {
+      return '{}'
+    }
+  }
+
+  const stringifyResponseBody = () => {
+    if (currentResponse?.data) {
+      const contentKey = Object.keys(currentResponse.data?.content)[0]
+      return JSON.stringify(currentResponse.data?.content[contentKey]?.schema?.properties, null, 2)
+    } else {
+      return '{}'
+    }
+  }
+
+  return (
+    <aside className={styles.apiDocsAside}>
+      <h2 className={styles.apiDocsAside_title}>{data.summary}</h2>
+      <h4 className={styles.apiDocsAside_subtitle}>
+        <span className={styles.apiDocsAside_subtitle_method} data-method={data.method}>
+          {data.method}
+        </span>{' '}
+        <span>{data.path}</span>
+      </h4>
+      {!['delete', 'get'].includes(data.method) && data?.requestBody?.content && (
+        <div className={styles.codeboxSection}>
+          <div className={styles.codeboxHeader}>
+            <h6 className={styles.codeboxTitle}>Request</h6>
+          </div>
+
+          <Codebox code={stringifyRequestBody()} />
+        </div>
+      )}
+      {Object.keys(data?.responses || {})?.length > 0 && (
+        <div className={styles.codeboxSection}>
+          <div className={`${styles.codeboxHeader}`}>
+            <h6 className={styles.codeboxTitle}>Response</h6>
+            <SelectGroup
+              size="small"
+              withSearch={false}
+              isMultiple={false}
+              clearable={false}
+              placeholder="200"
+              options={[
+                {
+                  list: httpStatusCodeOptions,
+                },
+              ]}
+              value={selectedResStatusCode}
+              onChange={(value) => {
+                setSelectedResStatusCode(value)
+              }}
+            />
+          </div>
+
+          <Codebox code={stringifyResponseBody()} />
+        </div>
+      )}
+    </aside>
+  )
+}
+
+export default DocsAside

package/src/layout/docsComponents/DocsAside/style.module.scss

@@ -0,0 +1,113 @@
+.apiDocsAside {
+  width: 22.5rem;
+  padding: 3rem 1.5rem;
+  background-color: #f0f1f2;
+
+  &_title {
+    font-size: 1.5rem;
+    line-height: 2rem;
+    font-weight: 600;
+    color: #12131a;
+    margin-bottom: 0.5rem;
+  }
+
+  &_subtitle {
+    margin-bottom: 2rem;
+
+    > span {
+      font-size: 1.25rem;
+      line-height: 1.75rem;
+      font-weight: 400;
+    }
+
+    &_method {
+      &[data-method='get'] {
+        color: #3a6cd1;
+      }
+
+      &[data-method='post'] {
+        color: #3aaa35;
+      }
+
+      &[data-method='put'] {
+        color: #faad14;
+      }
+
+      &[data-method='delete'] {
+        color: #da3f3f;
+      }
+
+      &[data-method='option'] {
+        color: #495d97;
+      }
+
+      &[data-method='head'] {
+        color: #9461c9;
+      }
+
+      &[data-method='patch'] {
+        color: #58e2c2;
+      }
+    }
+  }
+
+  .codeboxSection {
+    .codeboxHeader {
+      height: 2rem;
+      display: flex;
+      justify-content: space-between;
+      margin-bottom: 0.25rem;
+
+      h6 {
+        font-size: 1rem;
+        line-height: 1.25rem;
+        font-weight: 500;
+        color: #616874;
+      }
+    }
+
+    &:nth-of-type(2) {
+      margin-top: 3rem;
+    }
+
+    :global(.multiSelectGroup) {
+      :global(.selectDisplay) {
+        padding: 0;
+
+        :global(.select-label-container) {
+          min-width: 100%;
+          padding: 0;
+        }
+      }
+
+      :global(.optionsList .option) {
+        height: 1.5rem;
+        padding: 0;
+      }
+
+      .statusCodeOptionContainer {
+        display: flex;
+        align-items: center;
+        gap: 0.625rem;
+        padding-left: 0.75rem;
+
+        .statusCodeOptionCircle {
+          width: 0.625rem;
+          min-width: 0.625rem;
+          aspect-ratio: 1 / 1;
+          border-radius: 100%;
+        }
+      }
+    }
+  }
+
+  :global(.multiSelectGroup .selectDisplay),
+  :global(.multiSelectGroup) {
+    width: 6.25rem !important;
+    height: 1.5rem !important;
+  }
+
+  :global(.multiSelectGroup .selectDisplay .displayValueContainer .iconsContainer) {
+    padding-right: 0.75rem !important;
+  }
+}

package/src/layout/docsComponents/DocsContent/DocsContent.tsx

@@ -0,0 +1,51 @@
+import React, { useEffect, useRef } from 'react'
+import './style.scss'
+import { OverviewPage } from './OverviewPage'
+import { EndpointPage } from './EndpointPage'
+import { EndpointData, OverviewData } from 'src/layout/docsLayout'
+
+const DocsContent = ({
+  data,
+  activeType,
+  setActiveItemData,
+  setActiveType,
+  onProductNavigate,
+  apis,
+}: {
+  data: OverviewData | EndpointData
+  activeType: 'OVERVIEW' | 'ENDPOINT'
+  setActiveItemData: React.Dispatch<React.SetStateAction<OverviewData | EndpointData>>
+  setActiveType: React.Dispatch<React.SetStateAction<'OVERVIEW' | 'ENDPOINT'>>
+  onProductNavigate?: (productId: number) => void
+  apis: OverviewData[]
+}) => {
+  const containerRef = useRef(null)
+
+  useEffect(() => {
+    // This will scroll to the top when changing the overview
+    if (activeType === 'OVERVIEW' && containerRef?.current) {
+      containerRef?.current?.scrollTo({ top: 0, behavior: 'smooth' })
+    }
+  }, [data, activeType])
+  return (
+    <main ref={containerRef}>
+      {activeType === 'OVERVIEW' ? (
+        <OverviewPage
+          data={data as OverviewData}
+          setActiveItemData={setActiveItemData}
+          setActiveType={setActiveType}
+          onProductNavigate={onProductNavigate}
+          apis={apis}
+        />
+      ) : (
+        <EndpointPage
+          data={data as EndpointData}
+          setActiveType={setActiveType}
+          setActiveItemData={setActiveItemData}
+        />
+      )}
+    </main>
+  )
+}
+
+export default DocsContent