@digi-frontend/dgate-api-documentation 1.2.0 → 1.3.0

package/src/helpers/layout.helper.ts

@@ -0,0 +1,290 @@
+import { TransformedPathsArray } from '@entities/layout.type'
+import { OpenAPIFile, SecurityScheme } from '@entities/openApi'
+import { TransformedOpenApi } from '@entities/transformedOpenApi'
+
+const resolveRef = (ref: string, openApiJson: OpenAPIFile): Object => {
+  const parts = ref.replace(/^#\//, '').split('/')
+  return parts.reduce((obj, key) => obj?.[key], openApiJson)
+}
+
+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',
+        },
+      },
+      ...(openApiJson.components || {}),
+    }
+  }
+
+  if (!openApiJson.tags) {
+    openApiJson.tags = []
+  }
+
+  return {
+    ...openApiJson,
+    paths: transformPathsToArray(openApiJson),
+  } 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 = (openApiJson: OpenAPIFile): TransformedPathsArray | any => {
+  const paths: OpenAPIFile['paths'] = openApiJson.paths
+  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]
+          let headers = codeProps?.headers ?? {}
+
+          // ? Fix headers with items property
+          Object.keys(headers).map((header: string) => {
+            let headerObj = headers[header]
+            if (
+              headerObj?.schema &&
+              headerObj?.schema?.type &&
+              headerObj?.schema?.type != 'array'
+            ) {
+              delete headers[header]?.schema?.items
+            }
+          })
+
+          let schema = codeProps.content?.[contentType]?.schema
+          if (schema?.$ref) {
+            schema = resolveRef(schema?.$ref, openApiJson)
+          } else if (schema?.type == 'array' && schema?.items?.$ref) {
+            const resolvedItemSchema = resolveRef(schema.items.$ref, openApiJson)
+            schema = {
+              ...schema,
+              items: resolvedItemSchema,
+            }
+          }
+          // if the response content is not an array remove the (items) property
+          if (schema?.type !== 'array') {
+            const { items, ...schemaRest } = schema
+
+            schema = schemaRest
+          }
+
+          return {
+            code,
+            headers,
+            content: {
+              contentType,
+              schema: {
+                ...schema,
+                properties: JSON.stringify(schema?.properties || schema?.items?.properties),
+              },
+            },
+          }
+        }),
+      }
+
+      if (!obj.responses.find((item) => item.code == '200')) {
+        obj.responses.push({
+          code: '200',
+          content: {
+            contentType: 'application/json',
+            schema: {},
+          },
+          headers: {},
+        })
+      }
+      // Add parameters if it does not exist in the original JSON
+      if (!methodProps?.parameters) {
+        obj.parameters = []
+      } else {
+        obj.parameters = obj.parameters.map((param) => {
+          const { schema } = param
+          if (schema && schema?.items && schema?.type?.toLowerCase() != 'array') {
+            delete schema.items
+          }
+
+          return { ...param, schema }
+        })
+      }
+
+      // load response headers parameters
+
+      if (method.toLowerCase() != 'get') {
+        const contentType = Object.keys(methodProps?.requestBody?.content || {})[0]
+        let reqSchema = methodProps?.requestBody?.content?.[contentType]?.schema
+
+        if (reqSchema?.$ref) {
+          reqSchema = resolveRef(reqSchema.$ref, openApiJson)
+        } else if (reqSchema?.type === 'array' && reqSchema.items?.$ref) {
+          reqSchema = {
+            ...reqSchema,
+            items: resolveRef(reqSchema.items.$ref, openApiJson),
+          }
+        }
+
+        const requestBodyData = reqSchema
+          ? {
+              content: {
+                contentType,
+                schema: {
+                  ...reqSchema,
+                  properties: JSON.stringify(reqSchema?.properties || reqSchema?.items?.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
+        // ? Validate (rest) [parameters]
+        let copiedRest = structuredClone(rest || {})
+        if (copiedRest && copiedRest.parameters) {
+          copiedRest.parameters.map((param) => {
+            if (param && param?.schema?.items && param?.schema?.type?.toLowerCase() != 'array') {
+              delete param?.schema?.items
+            }
+            if (param && param?.schema?.items && param?.schema?.items?.type == 'array') {
+              param.schema.items.items = {}
+            }
+            return param
+          })
+        }
+
+        // Get the original responses from the rest object
+        const originalResponses = rest.responses || {}
+
+        methodAcc[type] = {
+          ...copiedRest,
+          tags,
+          summary,
+          responses: responses.reduce((respAcc, { code, content, headers }) => {
+            // Skip if:
+            // 1. This is a new code (not in original) AND
+            // 2. Both headers and content are empty
+            const isNewCode = !originalResponses[code]
+            const hasHeaders = Object.keys(headers || {}).length > 0
+            const hasContent =
+              Object.keys(validateBodyForResponse(content || {}, type) || {}).length > 0
+
+            if (isNewCode && !hasHeaders && !hasContent) {
+              return respAcc
+            }
+
+            const formattedHeaders: Record<string, any> = {}
+            if (headers) {
+              for (const [key, value] of Object.entries(headers)) {
+                if (
+                  value?.schema &&
+                  value?.schema?.items &&
+                  value?.schema?.type?.toLowerCase() != 'array'
+                ) {
+                  delete value?.schema?.items
+                }
+                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),
+                      },
+                    },
+                  }
+                : originalResponses[code]?.content || {},
+              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

@@ -0,0 +1,2 @@
+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/DocsAside/DocsAside.tsx

@@ -0,0 +1,112 @@
+import React, { useEffect, 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 DocsAside = ({ data }: { data: EndpointData }) => {
+  // Filter status codes to only include those with non-empty properties
+  const filteredStatusCodes = Object.keys(data?.responses || {}).filter((code) => {
+    const response = data.responses[code]
+    const contentType = Object.keys(response?.content || {})[0]
+    return response?.content?.[contentType]?.schema?.properties
+  })
+
+  // Create options for the select dropdown
+  const httpStatusCodeOptions = filteredStatusCodes.map((code) => ({
+    label: (
+      <div className={styles.statusCodeOptionContainer}>
+        <div
+          className={styles.statusCodeOptionCircle}
+          style={{ backgroundColor: handleStatusColor(code) }}
+        ></div>
+        <span>{code}</span>
+      </div>
+    ),
+    value: String(code),
+  }))
+
+  // Function to get default option
+  const getDefaultOption = () => {
+    const has200 = filteredStatusCodes.includes('200')
+    return has200
+      ? httpStatusCodeOptions.find((opt) => opt.value === '200')
+      : httpStatusCodeOptions[0] || null
+  }
+
+  useEffect(() => {
+    setSelectedResStatusCode(getDefaultOption())
+  }, [data])
+  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/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