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

package/src/layout/layout.tsx

@@ -0,0 +1,177 @@
+import { JSX, useEffect, useState } from 'react'
+import { Alert, Button } from 'digitinary-ui'
+import MethodsAccordion from '../components/MethodAccordion/MethodAccordion'
+import styles from './layout.module.css'
+import InfoForm from '../components/InfoForm/InfoForm'
+import SectionHead from '../components/SectionHead/SectionHead'
+import { transformOpenApiObject, transformOpenApiObjectToOrigin } from '../helpers/layout.helper'
+import { OpenAPIFile } from '../types/openApi'
+import LivePreview from '../components/LivePreview/LivePreview'
+import { FormikProvider, useFormik } from 'formik'
+import { schemaValidation } from '../validator/form.scheme'
+import { TransformedOpenApi } from '@entities/transformedOpenApi'
+import { methodColorMapping } from '../constants/index'
+import CommonDialog from '../components/dialog'
+
+interface ILayoutProps {
+  openApiJson?: OpenAPIFile
+  handleSave?: (values: unknown) => unknown
+  setIsFormDirty?: any
+  openApiErrors?: any
+}
+
+const Layout = ({
+  openApiJson,
+  handleSave,
+  setIsFormDirty,
+  openApiErrors,
+}: ILayoutProps): JSX.Element => {
+  const clonedOpenApiJson = structuredClone(openApiJson)
+  const transformedOpenApi = transformOpenApiObject(clonedOpenApiJson)
+  const formik = useFormik<TransformedOpenApi>({
+    initialValues: structuredClone(transformedOpenApi),
+    validationSchema: schemaValidation,
+    validateOnMount: true,
+    onSubmit: (values, { validateForm, resetForm, setSubmitting }) => {
+      // Handle save logic
+      try {
+        const originalOpenApiForm = transformOpenApiObjectToOrigin(values)
+        handleSave(originalOpenApiForm)
+        resetForm({
+          values: values, // You can reset it to the same values if you want
+        })
+
+        validateForm(values)
+      } catch (err) {
+        setSubmitting(false)
+      }
+    },
+  })
+  const { dirty, isValid, isSubmitting, values, setFieldValue, handleSubmit, errors } = formik
+  const [isPublishDialogOpen, setIsPublishDialogOpen] = useState(false)
+
+  const [openMethodIndex, setOpenMethodIndex] = useState<number | null>(null)
+
+  useEffect(() => {
+    if (setIsFormDirty) {
+      setIsFormDirty(dirty)
+    }
+  }, [dirty])
+
+  return (
+    <div className={styles.docsLayout}>
+      {dirty && (
+        <Alert className={styles.apiDocAlert} color="warning" severity="warning">
+          There are changes you made may not be saved
+        </Alert>
+      )}
+      <div className={styles.layoutContainer}>
+        <div className={`${styles.editorSide} ${styles.docSide}`}>
+          <SectionHead
+            className={styles.editorSectionHead_title}
+            text={
+              <div className={styles.editorSectionHead_content}>
+                API Documentation
+                <Button
+                  className={styles.methodForm_submitBtn}
+                  size="medium"
+                  fullWidth={false}
+                  type="submit"
+                  variant="contained"
+                  color="primary"
+                  onClick={() => setIsPublishDialogOpen(true)}
+                  disabled={!isValid || isSubmitting || !dirty}
+                >
+                  Save
+                </Button>
+              </div>
+            }
+          />
+          <FormikProvider value={formik}>
+            <InfoForm />
+          </FormikProvider>
+          <SectionHead className={styles.editorSectionHead} text="Endpoints" />
+          <FormikProvider value={formik}>
+            {values.paths.map((path, pathIndex) => (
+              <>
+                {path.methods
+                  .sort(
+                    (a, b) => methodColorMapping[a.type].order - methodColorMapping[b.type].order
+                  )
+                  .map((method, methodIndex) => (
+                    <MethodsAccordion
+                      tags={values.tags}
+                      method={method}
+                      path={path.path}
+                      setFieldValue={(key, value) => {
+                        const h = `paths[${pathIndex}].methods[${methodIndex}].${key}`
+                        setFieldValue(h, value)
+                      }}
+                      isOpen={openMethodIndex === parseInt(`${pathIndex}${methodIndex}`)}
+                      setIsOpen={(open) => setOpenMethodIndex(open ? parseInt(`${pathIndex}${methodIndex}`) : null)}
+                      errors={(formik.errors.paths?.[pathIndex] as any)?.methods?.[methodIndex]}
+                    />
+                  ))}
+              </>
+            ))}
+          </FormikProvider>
+        </div>
+        <div className={`${styles.livePreviewSide} ${styles.docSide}`}>
+          {transformedOpenApi && (
+            <FormikProvider value={formik}>
+              <LivePreview transformedData={transformedOpenApi} openApiErrors={openApiErrors} />
+            </FormikProvider>
+          )}
+        </div>
+      </div>
+      <CommonDialog
+        status="warning"
+        content={
+          <>
+            <h5
+              style={{
+                fontWeight: 600,
+                fontSize: '1.5rem',
+                lineHeight: '1.875rem',
+                color: '#FAAD14',
+                textAlign: 'center',
+                margin: 0,
+              }}
+            >
+              Publish Changes
+            </h5>
+            <p
+              style={{
+                textAlign: 'center',
+                fontWeight: 400,
+                fontSize: '1rem',
+                lineHeight: '1.4375rem',
+              }}
+            >
+              Are you sure to Publish the changes?
+            </p>
+          </>
+        }
+        onSubmit={{
+          onClick: () => {
+            handleSubmit()
+            setIsPublishDialogOpen(false)
+          },
+          text: 'Publish',
+          color: 'warning',
+          fullWidth: true,
+        }}
+        onCancel={{
+          text: 'Cancel',
+          color: 'action',
+          fullWidth: true,
+          variant: 'outlined',
+        }}
+        onClose={() => setIsPublishDialogOpen(false)}
+        open={isPublishDialogOpen}
+      />
+    </div>
+  )
+}
+
+export default Layout

package/src/types/docsLayout.type.ts

@@ -0,0 +1,7 @@
+export enum SectionEnum {
+  OVERVIEW = 'overview',
+  RESOURCE = 'resource',
+  API_SECTION = 'apiSection',
+  TAG_SECTION = 'tagSection',
+  ENDPOINTS_SECTION = 'endpointsSection',
+}

package/src/types/index.ts

@@ -0,0 +1,28 @@
+import { OpenAPIFile } from './openApi'
+
+export interface ApiSpecModel {
+  apiSpecId: string
+  contextPath: string
+  apiVersions: {
+    addVersionToContextPath: boolean
+    apiSpecId: string
+    name: string
+    metaData: {
+      version: string
+    }
+  }[]
+  associatedProduct: {
+    availableOnDevPortal: boolean
+    name: string
+    premium: boolean
+    productId: number
+  }
+  metaData: {
+    version: string
+    apiVersionOf: string
+    openApiJson: OpenAPIFile
+    tags: string[]
+    createdDateTime: string
+    lastUpdatedDateTime: string
+  }
+}

package/src/types/layout.type.ts

@@ -0,0 +1,32 @@
+import { HTTPMethod } from './openApi'
+
+export type TransformedMethod = {
+  type: HTTPMethod
+  tags: string[]
+  summary?: string
+  parameters: any
+  requestBody: {
+    content: {
+      contentType: string
+      schema: {
+        properties: string
+        type: string
+      }
+    }
+  }
+  responses: {
+    code: string
+    content: {
+      contentType?: string
+      schema?: unknown
+    }
+    headers: any
+  }[]
+}
+
+export type TransformedPath = {
+  path: string
+  methods: TransformedMethod[]
+}
+
+export type TransformedPathsArray = TransformedPath[]

package/src/types/openApi.ts

@@ -0,0 +1,109 @@
+export interface OpenAPIFile {
+  openapi: string
+  info: {
+    title: string
+    description: string
+    version: string
+  }
+  servers?: {
+    url: string
+    description?: string
+  }[]
+  paths: {
+    [path: string]: Partial<
+      Record<
+        HTTPMethod,
+        {
+          tags: string[]
+          responses: Responses
+          summary?: string
+          description?: string
+          parameters?: Parameter[]
+          requestBody?: RequestBody
+        }
+      >
+    >
+  }
+  components?: {
+    schemas?: {
+      [schemaName: string]: Schema
+    }
+    securitySchemes?: {
+      [schemeName: string]: SecurityScheme
+    }
+  }
+  security?: {
+    [schemeName: string]: string[]
+  }[]
+  tags?: {
+    name: string
+    description?: string
+    externalDocs?: {
+      url: string
+      description: string
+    }[]
+  }[]
+}
+
+export interface Tags {
+  name: string
+  description?: string
+  externalDocs?: {
+    url: string
+    description: string
+  }[]
+}
+
+export interface Parameter {
+  name: string
+  in: 'query' | 'header' | 'path' | 'cookie'
+  description?: string
+  required: boolean
+  schema: Schema
+}
+
+export interface RequestBody {
+  description?: string
+  required: boolean
+  content: {
+    [contentType: string]: {
+      schema: Schema
+    }
+  }
+}
+
+export interface Responses {
+  [statusCode: string]: {
+    description: string
+    headers?: any
+    content?: {
+      [contentType: string]: {
+        schema: Schema
+      }
+    }
+  }
+}
+
+interface Schema {
+  type?: string
+  format?: string
+  properties?: {
+    [propertyName: string]: Schema
+  }
+  items?: Schema
+  enum?: string[]
+  required?: string[]
+}
+
+export interface SecurityScheme {
+  type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect'
+  description?: string
+  name?: string
+  in?: 'query' | 'header' | 'cookie'
+  scheme?: string
+  bearerFormat?: string
+  flows?: any
+  openIdConnectUrl?: string
+}
+
+export type HTTPMethod = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace'

package/src/types/transformedOpenApi.ts

@@ -0,0 +1,52 @@
+import { TransformedPathsArray } from "./layout.type";
+
+export interface TransformedOpenApi {
+  openapi: string;
+  info: {
+    title: string;
+    description?: string;
+    version: string;
+  };
+  servers?: {
+    url: string;
+    description?: string;
+  }[];
+  paths: TransformedPathsArray;
+  components?: {
+    schemas?: {
+      [schemaName: string]: Schema;
+    };
+    securitySchemes?: {
+      [schemeName: string]: SecurityScheme;
+    };
+  };
+  security?: {
+    [schemeName: string]: string[];
+  }[];
+  tags?: {
+    name: string;
+    description?: string;
+  }[];
+}
+
+interface Schema {
+  type?: string;
+  format?: string;
+  properties?: {
+    [propertyName: string]: Schema;
+  };
+  items?: Schema;
+  enum?: string[];
+  required?: string[];
+}
+
+interface SecurityScheme {
+  type: "apiKey" | "http" | "oauth2" | "openIdConnect";
+  description?: string;
+  name?: string;
+  in?: "query" | "header" | "cookie";
+  scheme?: string;
+  bearerFormat?: string;
+  flows?: any;
+  openIdConnectUrl?: string;
+}

package/src/utils/index.ts

@@ -0,0 +1,15 @@
+import { toast } from "react-toastify"
+
+export const copyToClipboard = async (text: string) => {
+  try {
+    await navigator.clipboard.writeText(text)
+    toast.success('Copied to your clipboard!')
+  } catch (err) {
+    return err
+  }
+}
+
+export const capitalizeFirstLetter = (text: string) => {
+  if (!text) return ''
+  return text.charAt(0).toUpperCase() + text.slice(1).toLowerCase()
+}

package/src/validator/form.scheme.ts

@@ -0,0 +1,96 @@
+import * as yup from 'yup'
+export const schemaValidation = yup.object({
+  openapi: yup.string().required(),
+  info: yup
+    .object({
+      title: yup.string().trim().required('API Name is required.'),
+      description: yup.string().trim().required('API Description is required.'),
+      version: yup.string().required('API Version is required'),
+    })
+    .required(),
+  servers: yup
+    .array(
+      yup.object({
+        url: yup
+          .string()
+          .required()
+          .test(
+            'is-url-or-slash',
+            'Must be a valid URL or "/"',
+            (value) => value === '/' || yup.string().url().isValidSync(value)
+          ),
+        description: yup.string().optional(),
+      })
+    )
+    .optional(),
+  paths: yup
+    .array()
+    .of(
+      yup.object().shape({
+        path: yup.string().required(),
+        methods: yup
+          .array()
+          .of(
+            yup.object().shape({
+              summary: yup.string().trim().required('Endpoint Name is required.'),
+              description: yup.string().trim().optional(),
+              type: yup.string().optional(),
+              tags: yup.array().of(yup.string()).optional(),
+              requestBody: yup.mixed().optional(),
+            })
+          )
+          .required(),
+      })
+    )
+    .required(),
+  components: yup
+    .object({
+      schemas: yup
+        .lazy((value) =>
+          yup.object(
+            value
+              ? Object.keys(value).reduce((acc, key) => {
+                  acc[key] = yup.object({
+                    type: yup.string().optional(),
+                    format: yup.string().optional(),
+                    properties: yup
+                      .lazy((props) =>
+                        yup.object(
+                          props
+                            ? Object.keys(props).reduce((acc, propKey) => {
+                                acc[propKey] = yup.mixed()
+                                return acc
+                              }, {})
+                            : {}
+                        )
+                      )
+                      .optional(),
+                    items: yup.mixed().optional(),
+                    enum: yup.array(yup.string()).optional(),
+                    required: yup.array(yup.string()).optional(),
+                  })
+                  return acc
+                }, {})
+              : {}
+          )
+        )
+        .optional(),
+      securitySchemes: yup.object().optional(),
+    })
+    .optional(),
+  security: yup
+    .array(
+      yup.object().shape({
+        schemeName: yup.array(yup.string()).optional(),
+      })
+    )
+    .optional(),
+  tags: yup
+    .array(
+      yup.object({
+        name: yup.string().required(),
+        description: yup.string().optional(),
+      })
+    )
+    .optional(),
+})

package/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "module": "ESNext",
+    "target": "ES6",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "declaration": true,
+    "declarationDir": "dist/types",
+    "jsx": "react-jsx",
+    "strict": false,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "importHelpers": true,
+    "resolveJsonModule": true,
+    "plugins": [
+      {
+        "name": "typescript-plugin-css-modules"
+      }
+    ],
+    "baseUrl": "./",
+    "paths": {
+      "@components/*": ["src/components/*"],
+      "@icons": ["src/assets/icons"],
+      "@constants/*": ["src/constants/*"],
+      "@entities/*": ["src/types/*"],
+      "@helpers/*": ["src/helpers/*"]
+    }
+  },
+  "include": ["src", "src/global.d.ts"], // Add "src/global.d.ts" here
+  "exclude": ["node_modules", "dist"]
+}