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
This commit is contained in:
Shahed Nasser
GitHub
@@ -0,0 +1,69 @@
|
||||
import SidebarProvider from "@/providers/sidebar"
|
||||
import Sidebar from "@/components/Sidebar"
|
||||
import clsx from "clsx"
|
||||
import "../../../css/globals.css"
|
||||
import BaseSpecsProvider from "@/providers/base-specs"
|
||||
import Navbar from "@/components/Navbar"
|
||||
import ColorModeProvider from "@/providers/color-mode"
|
||||
import { Inter } from "next/font/google"
|
||||
import { Roboto_Mono } from "next/font/google"
|
||||
import AnalyticsProvider from "@/providers/analytics"
|
||||
import NavbarProvider from "@/providers/navbar"
|
||||
import ModalProvider from "../../../providers/modal"
|
||||
|
||||
export const metadata = {
|
||||
title: "Medusa API Reference",
|
||||
description: "Check out Medusa's API reference",
|
||||
}
|
||||
|
||||
const inter = Inter({
|
||||
subsets: ["latin"],
|
||||
variable: "--font-inter",
|
||||
weight: ["400", "500"],
|
||||
})
|
||||
|
||||
const robotoMono = Roboto_Mono({
|
||||
subsets: ["latin"],
|
||||
variable: "--font-roboto-mono",
|
||||
})
|
||||
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<html lang="en" className={clsx("h-full w-full")}>
|
||||
<body
|
||||
className={clsx(
|
||||
inter.variable,
|
||||
robotoMono.variable,
|
||||
"bg-docs-bg dark:bg-docs-bg-dark font-base text-medium h-full w-full",
|
||||
"text-medusa-fg-subtle dark:text-medusa-fg-subtle-dark"
|
||||
)}
|
||||
>
|
||||
<AnalyticsProvider>
|
||||
<ModalProvider>
|
||||
<ColorModeProvider>
|
||||
<BaseSpecsProvider>
|
||||
<SidebarProvider>
|
||||
<NavbarProvider>
|
||||
<div className="w-full">
|
||||
<Navbar />
|
||||
<div className="max-w-xxl mx-auto flex w-full px-1.5">
|
||||
<Sidebar />
|
||||
<main className="lg:w-api-ref-main relative mt-4 w-full flex-1 lg:mt-7">
|
||||
{children}
|
||||
</main>
|
||||
</div>
|
||||
</div>
|
||||
</NavbarProvider>
|
||||
</SidebarProvider>
|
||||
</BaseSpecsProvider>
|
||||
</ColorModeProvider>
|
||||
</ModalProvider>
|
||||
</AnalyticsProvider>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 253 KiB |
@@ -0,0 +1,64 @@
|
||||
import AreaProvider from "@/providers/area"
|
||||
import AdminDescription from "../../_mdx/admin.mdx"
|
||||
import StoreDescription from "../../_mdx/store.mdx"
|
||||
import ClientLibraries from "../../_mdx/client-libraries.mdx"
|
||||
import Section from "@/components/Section"
|
||||
import Tags from "@/components/Tags"
|
||||
import type { Area } from "@/types/openapi"
|
||||
import DividedLayout from "@/layouts/Divided"
|
||||
import capitalize from "@/utils/capitalize"
|
||||
import PageTitleProvider from "../../../providers/page-title"
|
||||
|
||||
type ReferencePageProps = {
|
||||
params: {
|
||||
area: Area
|
||||
}
|
||||
}
|
||||
|
||||
const ReferencePage = async ({ params: { area } }: ReferencePageProps) => {
|
||||
return (
|
||||
<AreaProvider area={area}>
|
||||
<PageTitleProvider>
|
||||
<h1 className="!text-h2 block lg:hidden">
|
||||
Medusa {capitalize(area)} API Reference
|
||||
</h1>
|
||||
<DividedLayout
|
||||
mainContent={
|
||||
<Section>
|
||||
<h1 className="!text-h2 hidden lg:block">
|
||||
Medusa {capitalize(area)} API Reference
|
||||
</h1>
|
||||
{area.includes("admin") && <AdminDescription />}
|
||||
{area.includes("store") && <StoreDescription />}
|
||||
</Section>
|
||||
}
|
||||
codeContent={<ClientLibraries />}
|
||||
className="flex-col-reverse"
|
||||
/>
|
||||
<Tags />
|
||||
</PageTitleProvider>
|
||||
</AreaProvider>
|
||||
)
|
||||
}
|
||||
|
||||
export default ReferencePage
|
||||
|
||||
export function generateMetadata({ params: { area } }: ReferencePageProps) {
|
||||
return {
|
||||
title: `Medusa ${capitalize(area)} API Reference`,
|
||||
description: `REST API reference for the Medusa ${area} API. This reference includes code snippets and examples for Medusa JS Client and cURL.`,
|
||||
}
|
||||
}
|
||||
|
||||
export const dynamicParams = false
|
||||
|
||||
export async function generateStaticParams() {
|
||||
return [
|
||||
{
|
||||
area: "admin",
|
||||
},
|
||||
{
|
||||
area: "store",
|
||||
},
|
||||
]
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 253 KiB |
@@ -0,0 +1,150 @@
|
||||
import OpenAPIParser from "@readme/openapi-parser"
|
||||
import algoliasearch from "algoliasearch"
|
||||
import type { ExpandedDocument, Operation } from "../../../types/openapi"
|
||||
import path from "path"
|
||||
import getPathsOfTag from "../../../utils/get-paths-of-tag"
|
||||
import getSectionId from "../../../utils/get-section-id"
|
||||
import { NextResponse } from "next/server"
|
||||
import { JSDOM } from "jsdom"
|
||||
import capitalize from "../../../utils/capitalize"
|
||||
import getUrl from "../../../utils/get-url"
|
||||
|
||||
export async function GET() {
|
||||
const algoliaClient = algoliasearch(
|
||||
process.env.NEXT_PUBLIC_ALGOLIA_APP_ID || "",
|
||||
process.env.ALGOLIA_WRITE_API_KEY || ""
|
||||
)
|
||||
const index = algoliaClient.initIndex(
|
||||
process.env.NEXT_PUBLIC_ALGOLIA_INDEX_NAME || ""
|
||||
)
|
||||
|
||||
// retrieve tags and their operations to index them
|
||||
const indices: Record<string, any>[] = []
|
||||
for (const area of ["store", "admin"]) {
|
||||
const defaultIndexData = {
|
||||
version: ["current"],
|
||||
lang: "en",
|
||||
_tags: ["api", area],
|
||||
}
|
||||
// find and parse static headers from pages
|
||||
const dom = await JSDOM.fromURL(getUrl(area))
|
||||
const headers = dom.window.document.querySelectorAll("h2")
|
||||
headers.forEach((header) => {
|
||||
if (!header.textContent) {
|
||||
return
|
||||
}
|
||||
|
||||
const objectID = getSectionId([header.textContent])
|
||||
const url = getUrl(area, objectID)
|
||||
indices.push({
|
||||
objectID: getObjectId(area, `${objectID}-mdx-section`),
|
||||
hierarchy: getHierarchy(area, [header.textContent]),
|
||||
type: `content`,
|
||||
content: header.textContent,
|
||||
url,
|
||||
url_without_variables: url,
|
||||
url_without_anchor: url,
|
||||
...defaultIndexData,
|
||||
})
|
||||
})
|
||||
|
||||
// find and index tag and operations
|
||||
const baseSpecs = (await OpenAPIParser.parse(
|
||||
path.join(process.cwd(), `specs/${area}/openapi.yaml`)
|
||||
)) as ExpandedDocument
|
||||
|
||||
await Promise.all(
|
||||
baseSpecs.tags?.map(async (tag) => {
|
||||
const tagName = getSectionId([tag.name])
|
||||
const url = getUrl(area, tagName)
|
||||
indices.push({
|
||||
objectID: getObjectId(area, tagName),
|
||||
hierarchy: getHierarchy(area, [tag.name]),
|
||||
type: "lvl1",
|
||||
content: null,
|
||||
url,
|
||||
url_without_variables: url,
|
||||
url_without_anchor: url,
|
||||
...defaultIndexData,
|
||||
})
|
||||
const paths = await getPathsOfTag(tagName, area)
|
||||
|
||||
Object.values(paths.paths).forEach((path) => {
|
||||
Object.values(path).forEach((op) => {
|
||||
const operation = op as Operation
|
||||
const operationName = getSectionId([
|
||||
tag.name,
|
||||
operation.operationId,
|
||||
])
|
||||
const url = getUrl(area, operationName)
|
||||
indices.push({
|
||||
objectID: getObjectId(area, operationName),
|
||||
hierarchy: getHierarchy(area, [tag.name, operation.summary]),
|
||||
type: "content",
|
||||
content: operation.summary,
|
||||
content_camel: operation.summary,
|
||||
url,
|
||||
url_without_variables: url,
|
||||
url_without_anchor: url,
|
||||
...defaultIndexData,
|
||||
})
|
||||
|
||||
// index its description
|
||||
const operationDescriptionId = getSectionId([
|
||||
tag.name,
|
||||
operation.operationId,
|
||||
operation.description.substring(
|
||||
0,
|
||||
Math.min(20, operation.description.length)
|
||||
),
|
||||
])
|
||||
|
||||
indices.push({
|
||||
objectID: getObjectId(area, operationDescriptionId),
|
||||
hierarchy: getHierarchy(area, [
|
||||
tag.name,
|
||||
operation.summary,
|
||||
operation.description,
|
||||
]),
|
||||
type: "content",
|
||||
content: operation.description,
|
||||
content_camel: operation.description,
|
||||
url,
|
||||
url_without_variables: url,
|
||||
url_without_anchor: url,
|
||||
...defaultIndexData,
|
||||
})
|
||||
})
|
||||
})
|
||||
}) || []
|
||||
)
|
||||
}
|
||||
|
||||
if (indices.length) {
|
||||
await index.saveObjects(indices, {
|
||||
autoGenerateObjectIDIfNotExist: true,
|
||||
})
|
||||
}
|
||||
|
||||
return NextResponse.json({
|
||||
message: "done",
|
||||
})
|
||||
}
|
||||
|
||||
function getObjectId(area: string, objectName: string): string {
|
||||
return `${area}_${objectName}`
|
||||
}
|
||||
|
||||
function getHierarchy(area: string, levels: string[]): Record<string, string> {
|
||||
const heirarchy: Record<string, string> = {
|
||||
lvl0: `${capitalize(area)} API Reference`,
|
||||
}
|
||||
|
||||
let counter = 1
|
||||
levels.forEach((level) => {
|
||||
heirarchy[`lvl${counter}`] = level
|
||||
counter++
|
||||
})
|
||||
|
||||
return heirarchy
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
import { NextResponse } from "next/server"
|
||||
import path from "path"
|
||||
import OpenAPIParser from "@readme/openapi-parser"
|
||||
import getPathsOfTag from "@/utils/get-paths-of-tag"
|
||||
import type { ExpandedDocument } from "@/types/openapi"
|
||||
|
||||
export async function GET(request: Request) {
|
||||
const { searchParams } = new URL(request.url)
|
||||
const area = searchParams.get("area")
|
||||
const expand = searchParams.get("expand")
|
||||
if (area !== "admin" && area !== "store") {
|
||||
return NextResponse.json(
|
||||
{
|
||||
success: false,
|
||||
message: `area ${area} is not allowed`,
|
||||
},
|
||||
{
|
||||
status: 400,
|
||||
}
|
||||
)
|
||||
}
|
||||
const baseSpecs = (await OpenAPIParser.parse(
|
||||
path.join(process.cwd(), `specs/${area}/openapi.yaml`)
|
||||
)) as ExpandedDocument
|
||||
|
||||
if (expand) {
|
||||
const paths = await getPathsOfTag(expand, area)
|
||||
if (paths) {
|
||||
baseSpecs.expandedTags = {}
|
||||
baseSpecs.expandedTags[expand] = paths.paths
|
||||
}
|
||||
}
|
||||
|
||||
return NextResponse.json(baseSpecs, {
|
||||
status: 200,
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,41 @@
|
||||
import { NextResponse } from "next/server"
|
||||
import path from "path"
|
||||
import getPathsOfTag from "@/utils/get-paths-of-tag"
|
||||
|
||||
export async function GET(request: Request) {
|
||||
const { searchParams } = new URL(request.url)
|
||||
const tagName = searchParams.get("tagName") || ""
|
||||
const area = searchParams.get("area")
|
||||
|
||||
if (area !== "admin" && area !== "store") {
|
||||
return NextResponse.json(
|
||||
{
|
||||
success: false,
|
||||
message: `area ${area} is not allowed`,
|
||||
},
|
||||
{
|
||||
status: 400,
|
||||
}
|
||||
)
|
||||
}
|
||||
|
||||
// this is just to ensure that vercel picks up these files on build
|
||||
path.join(process.cwd(), "specs/admin/code_samples")
|
||||
path.join(process.cwd(), "specs/admin/components")
|
||||
path.join(process.cwd(), "specs/admin/paths")
|
||||
path.join(process.cwd(), "specs/store/code_samples")
|
||||
path.join(process.cwd(), "specs/store/components")
|
||||
path.join(process.cwd(), "specs/store/paths")
|
||||
|
||||
// get path files
|
||||
const paths = await getPathsOfTag(tagName, area)
|
||||
|
||||
return NextResponse.json(
|
||||
{
|
||||
paths: paths.paths,
|
||||
},
|
||||
{
|
||||
status: 200,
|
||||
}
|
||||
)
|
||||
}
|
||||
Reference in New Issue
Block a user