api-ref: custom API reference (#4770)

* initialized next.js project

* finished markdown sections

* added operation schema component

* change page metadata

* eslint fixes

* fixes related to deployment

* added response schema

* resolve max stack issue

* support for different property types

* added support for property types

* added loading for components

* added more loading

* type fixes

* added oneOf type

* removed console

* fix replace with push

* refactored everything

* use static content for description

* fixes and improvements

* added code examples section

* fix path name

* optimizations

* fixed tag navigation

* add support for admin and store references

* general enhancements

* optimizations and fixes

* fixes and enhancements

* added search bar

* loading enhancements

* added loading

* added code blocks

* added margin top

* add empty response text

* fixed oneOf parameters

* added path and query parameters

* general fixes

* added base path env variable

* small fix for arrays

* enhancements

* design enhancements

* general enhancements

* fix isRequired

* added enum values

* enhancements

* general fixes

* general fixes

* changed oas generation script

* additions to the introduction section

* added copy button for code + other enhancements

* fix response code block

* fix metadata

* formatted store introduction

* move sidebar logic to Tags component

* added test env variables

* fix code block bug

* added loading animation

* added expand param + loading

* enhance operation loading

* made responsive + improvements

* added loading provider

* fixed loading

* adjustments for small devices

* added sidebar label for endpoints

* added feedback component

* fixed analytics

* general fixes

* listen to scroll for other headings

* added sample env file

* update api ref files + support new fields

* fix for external docs link

* added new sections

* fix last item in sidebar not showing

* move docs content to www/docs

* change redirect url

* revert change

* resolve build errors

* configure rewrites

* changed to environment variable url

* revert changing environment variable name

* add environment variable for API path

* fix links

* fix tailwind settings

* remove vercel file

* reconfigured api route

* move api page under api

* fix page metadata

* fix external link in navigation bar

* update api spec

* updated api specs

* fixed google lint error

* add max-height on request samples

* add padding before loading

* fix for one of name

* fix undefined types

* general fixes

* remove response schema example

* redesigned navigation bar

* redesigned sidebar

* fixed up paddings

* added feedback component + report issue

* fixed up typography, padding, and general styling

* redesigned code blocks

* optimization

* added error timeout

* fixes

* added indexing with algolia + fixes

* fix errors with algolia script

* redesign operation sections

* fix heading scroll

* design fixes

* fix padding

* fix padding + scroll issues

* fix scroll issues

* improve scroll performance

* fixes for safari

* optimization and fixes

* fixes to docs + details animation

* padding fixes for code block

* added tab animation

* fixed incorrect link

* added selection styling

* fix lint errors

* redesigned details component

* added detailed feedback form

* api reference fixes

* fix tabs

* upgrade + fixes

* updated documentation links

* optimizations to sidebar items

* fix spacing in sidebar item

* optimizations and fixes

* fix endpoint path styling

* remove margin

* final fixes

* change margin on small devices

* generated OAS

* fixes for mobile

* added feedback modal

* optimize dark mode button

* fixed color mode useeffect

* minimize dom size

* use new style system

* radius and spacing design system

* design fixes

* fix eslint errors

* added meta files

* change cron schedule

* fix docusaurus configurations

* added operating system to feedback data

* change content directory name

* fixes to contribution guidelines

* revert renaming content

* added api-reference to documentation workflow

* fixes for search

* added dark mode + fixes

* oas fixes

* handle bugs

* added code examples for clients

* changed tooltip text

* change authentication to card

* change page title based on selected section

* redesigned mobile navbar

* fix icon colors

* fix key colors

* fix medusa-js installation command

* change external regex in algolia

* change changeset

* fix padding on mobile

* fix hydration error

* update depedencies

www/api-reference/utils/capitalize.ts

@@ -0,0 +1,3 @@
+export default function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase()
+}

www/api-reference/utils/check-element-in-viewport.ts

@@ -0,0 +1,16 @@
+export default function checkElementInViewport(
+  element: Element,
+  percentage = 100,
+  height?: number
+) {
+  const rect = element.getBoundingClientRect()
+  const windowHeight =
+    height || window.innerHeight || document.documentElement.clientHeight
+
+  return !(
+    Math.floor(100 - ((rect.top >= 0 ? 0 : rect.top) / +-rect.height) * 100) <
+      percentage ||
+    Math.floor(100 - ((rect.bottom - windowHeight) / rect.height) * 100) <
+      percentage
+  )
+}

www/api-reference/utils/check-required.ts

@@ -0,0 +1,5 @@
+import type { SchemaObject } from "@/types/openapi"
+
+export default function checkRequired(schema: SchemaObject, property?: string) {
+  return property !== undefined && schema.required?.includes(property)
+}

www/api-reference/utils/check-sidebar-item-visibility.ts

@@ -0,0 +1,21 @@
+export default function checkSidebarItemVisibility(
+  item: Element,
+  options?: {
+    topMargin?: number
+  }
+) {
+  const sidebar = document.getElementById("sidebar")
+  if (!sidebar) {
+    return false
+  }
+
+  const { topMargin = 0 } = options || {}
+  const sidebarBoundingRect = sidebar.getBoundingClientRect()
+  const activeItemBoundingRect = item.getBoundingClientRect()
+
+  return (
+    activeItemBoundingRect.top >= topMargin &&
+    activeItemBoundingRect.top - sidebarBoundingRect.height + topMargin < 0 &&
+    activeItemBoundingRect.bottom > 0
+  )
+}

www/api-reference/utils/get-base-url.ts

@@ -0,0 +1,3 @@
+export default function getBaseUrl() {
+  return process.env.NEXT_PUBLIC_BASE_URL || "http://locahost:3000"
+}

www/api-reference/utils/get-link-with-base-path.ts

@@ -0,0 +1,3 @@
+export default function getLinkWithBasePath(path: string): string {
+  return `${process.env.NEXT_PUBLIC_BASE_PATH || "/api"}${path}`
+}

www/api-reference/utils/get-paths-of-tag.ts

@@ -0,0 +1,74 @@
+import path from "path"
+import { promises as fs } from "fs"
+import type { OpenAPIV3 } from "openapi-types"
+import type { Operation, Document } from "@/types/openapi"
+import readSpecDocument from "./read-spec-document"
+import getSectionId from "./get-section-id"
+import OpenAPIParser from "@readme/openapi-parser"
+
+type ParsedPathItemObject = OpenAPIV3.PathItemObject<Operation> & {
+  operationPath?: string
+}
+
+export default async function getPathsOfTag(
+  tagName: string,
+  area: string
+): Promise<Document> {
+  // get path files
+  const basePath = path.join(process.cwd(), `specs/${area}/paths`)
+
+  const files = await fs.readdir(basePath)
+
+  // read the path documents
+  let documents: ParsedPathItemObject[] = await Promise.all(
+    files.map(async (file) => {
+      const fileContent = (await readSpecDocument(
+        path.join(basePath, file)
+      )) as OpenAPIV3.PathItemObject<Operation>
+
+      return {
+        ...fileContent,
+        operationPath: `/${file
+          .replaceAll("_", "/")
+          .replace(/\.[A-Za-z]+$/, "")}`,
+      }
+    })
+  )
+
+  // filter out operations not related to the passed tag
+  documents = documents.filter((document) =>
+    Object.values(document).some((operation) => {
+      if (typeof operation !== "object" || !("tags" in operation)) {
+        return false
+      }
+
+      return operation.tags?.some((tag) => getSectionId([tag]) === tagName)
+    })
+  )
+
+  // dereference the references in the paths
+  let paths: Document = {
+    paths: {},
+    // These attributes are only for validation purposes
+    openapi: "3.0.0",
+    info: {
+      title: "Medusa API",
+      version: "1.0.0",
+    },
+  }
+
+  documents.forEach((document) => {
+    const documentPath = document.operationPath || ""
+    delete document.operationPath
+    paths.paths[documentPath] = document
+  })
+
+  // resolve references in paths
+  paths = (await OpenAPIParser.dereference(
+    `${basePath}/`,
+    paths,
+    {}
+  )) as unknown as Document
+
+  return paths
+}

www/api-reference/utils/get-section-id.ts

@@ -0,0 +1,6 @@
+import slugify from "slugify"
+
+export default function getSectionId(path: string[]) {
+  path = path.map((p) => slugify(p.trim().toLowerCase()))
+  return path.join("_")
+}

www/api-reference/utils/get-security-schema-type-name.ts

@@ -0,0 +1,16 @@
+import { OpenAPIV3 } from "openapi-types"
+
+export default function getSecuritySchemaTypeName(
+  securitySchema: OpenAPIV3.SecuritySchemeObject
+) {
+  switch (securitySchema.type) {
+    case "apiKey":
+      return "API Key"
+    case "http":
+      return "HTTP"
+    case "oauth2":
+      return "OAuth2"
+    case "openIdConnect":
+      return "OpenID Connect"
+  }
+}

www/api-reference/utils/get-tag-child-sidebar-items.ts

@@ -0,0 +1,27 @@
+import type { SidebarItemType } from "@/providers/sidebar"
+import type { Operation, PathsObject } from "@/types/openapi"
+import type { OpenAPIV3 } from "openapi-types"
+import getSectionId from "./get-section-id"
+
+export default function getTagChildSidebarItems(
+  paths: PathsObject
+): SidebarItemType[] {
+  const items: SidebarItemType[] = []
+  Object.entries(paths).forEach(([, operations]) => {
+    Object.entries(operations).map(([method, operation]) => {
+      const definedOperation = operation as Operation
+      const definedMethod = method as OpenAPIV3.HttpMethods
+      items.push({
+        path: getSectionId([
+          ...(definedOperation.tags || []),
+          definedOperation.operationId,
+        ]),
+        title: definedOperation.summary || definedOperation.operationId,
+        method: definedMethod,
+        loaded: true,
+      })
+    })
+  })
+
+  return items
+}

www/api-reference/utils/get-url.ts

@@ -0,0 +1,5 @@
+import getBaseUrl from "./get-base-url"
+
+export default function getUrl(area: string, tagName?: string): string {
+  return `${getBaseUrl()}/api/${area}#${tagName}`
+}

www/api-reference/utils/read-spec-document.ts

@@ -0,0 +1,8 @@
+import { promises as fs } from "fs"
+import { OpenAPIV3 } from "openapi-types"
+import { parseDocument } from "yaml"
+
+export default async function readSpecDocument(filePath: string) {
+  const fileContent = await fs.readFile(filePath, "utf-8")
+  return parseDocument(fileContent).toJS() as OpenAPIV3.PathItemObject
+}

www/api-reference/utils/swr-fetcher.ts

@@ -0,0 +1,9 @@
+const fetcher = async <JSON = any>(
+  input: RequestInfo,
+  init?: RequestInit
+): Promise<JSON> => {
+  const res = await fetch(input, init)
+  return res.json()
+}
+
+export default fetcher