asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: prep for v2 documentation (#6710)

Browse Source 
This PR includes documentation that preps for v2 docs (but doesn't introduce new docs).

_Note: The number of file changes in the PR is due to find-and-replace within the `references` which is unavoidable. Let me know if I should move it to another PR._

## Changes

- Change Medusa version in base OAS used for v2.
- Fix to docblock generator related to not catching all path parameters.
- Added typedoc plugin that generates ER Diagrams, which will be used specifically for data model references in commerce modules.
- Changed OAS tool to output references in `www/apps/api-reference/specs-v2` directory when the `--v2` option is used.
- Added a version switcher to the API reference to switch between V1 and V2. This switcher is enabled by an environment variable, so it won't be visible/usable at the moment.
- Upgraded docusaurus to v3.0.1
- Added new Vale rules to ensure correct spelling of Medusa Admin and module names.
- Added new components to the `docs-ui` package that will be used in future documentation changes.
This commit is contained in:
Shahed Nasser
2024-03-18 09:47:35 +02:00
committed by GitHub
parent 56a6ec0227
commit bb87db8342
2008 changed files with 15716 additions and 10536 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
www/apps/api-reference/app/api/[area]/layout.tsx
View File

@@ -1,10 +1,9 @@
import clsx from "clsx"
import "../../../css/globals.css"
import "../../globals.css"
import Navbar from "@/components/Navbar"
import { Inter } from "next/font/google"
import { Roboto_Mono } from "next/font/google"
import Providers from "../../../providers"
import { Sidebar } from "docs-ui"
import { WideLayout } from "docs-ui"
import { Inter, Roboto_Mono } from "next/font/google"
import clsx from "clsx"
export const metadata = {
title: "Medusa API Reference",
@@ -28,31 +27,12 @@ export default function RootLayout({
children: React.ReactNode
}) {
return (
<html lang="en" className={clsx("h-full w-full")}>
<body
className={clsx(
inter.variable,
robotoMono.variable,
"bg-docs-bg font-base text-medium w-full",
"text-medusa-fg-subtle",
"h-screen overflow-hidden"
)}
>
<Providers>
<Navbar />
<div
className="w-full h-[calc(100%-57px)] overflow-y-scroll overflow-x-hidden"
id="main"
>
<div className="max-w-xxl mx-auto flex w-full px-1.5">
<Sidebar />
<main className="lg:w-ref-main relative mt-4 w-full flex-1 lg:mt-7">
{children}
</main>
</div>
</div>
</Providers>
</body>
</html>
<WideLayout
ProvidersComponent={Providers}
NavbarComponent={Navbar}
bodyClassName={clsx(inter.variable, robotoMono.variable)}
>
{children}
</WideLayout>
)
}

9
www/apps/api-reference/app/api/[area]/page.tsx
View File

@@ -8,6 +8,7 @@ import type { Area } from "@/types/openapi"
import DividedLayout from "@/layouts/Divided"
import { capitalize } from "docs-ui"
import PageTitleProvider from "../../../providers/page-title"
import PageHeading from "../../../components/PageHeading"
type ReferencePageProps = {
params: {
@@ -19,15 +20,11 @@ const ReferencePage = async ({ params: { area } }: ReferencePageProps) => {
return (
<AreaProvider area={area}>
<PageTitleProvider>
<h1 className="!text-h2 block lg:hidden">
Medusa {capitalize(area)} API Reference
</h1>
<PageHeading className="!text-h2 block lg:hidden" />
<DividedLayout
mainContent={
<Section>
<h1 className="!text-h2 hidden lg:block">
Medusa {capitalize(area)} API Reference
</h1>
<PageHeading className="!text-h2 hidden lg:block" />
{area.includes("admin") && <AdminDescription />}
{area.includes("store") && <StoreDescription />}
</Section>

0
www/apps/api-reference/app/api/algolia/route.tsx → www/apps/api-reference/app/api/algolia/route.ts
View File

12
www/apps/api-reference/app/api/base-specs/route.ts
View File

@@ -2,11 +2,15 @@ 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"
import type { ExpandedDocument, Version } from "@/types/openapi"
export async function GET(request: Request) {
const { searchParams } = new URL(request.url)
const area = searchParams.get("area")
const version =
process.env.NEXT_PUBLIC_VERSIONING === "true"
? (searchParams.get("version") as Version) || "1"
: "1"
const expand = searchParams.get("expand")
if (area !== "admin" && area !== "store") {
return NextResponse.json(
@@ -20,7 +24,11 @@ export async function GET(request: Request) {
)
}
const baseSpecs = (await OpenAPIParser.parse(
path.join(process.cwd(), `specs/${area}/openapi.yaml`)
path.join(
process.cwd(),
version === "1" ? "specs" : "specs-v2",
`${area}/openapi.yaml`
)
)) as ExpandedDocument
if (expand) {

13
www/apps/api-reference/app/api/tag/route.ts
View File

@@ -1,11 +1,16 @@
import { NextResponse } from "next/server"
import path from "path"
import getPathsOfTag from "@/utils/get-paths-of-tag"
import { Version } from "../../../types/openapi"
export async function GET(request: Request) {
const { searchParams } = new URL(request.url)
const tagName = searchParams.get("tagName") || ""
const area = searchParams.get("area")
const version =
process.env.NEXT_PUBLIC_VERSIONING === "true"
? (searchParams.get("version") as Version) || "1"
: "1"
if (area !== "admin" && area !== "store") {
return NextResponse.json(
@@ -26,9 +31,15 @@ export async function GET(request: Request) {
path.join(process.cwd(), "specs/store/code_samples")
path.join(process.cwd(), "specs/store/components")
path.join(process.cwd(), "specs/store/paths")
path.join(process.cwd(), "specs-v2/admin/code_samples")
path.join(process.cwd(), "specs-v2/admin/components")
path.join(process.cwd(), "specs-v2/admin/paths")
path.join(process.cwd(), "specs-v2/store/code_samples")
path.join(process.cwd(), "specs-v2/store/components")
path.join(process.cwd(), "specs-v2/store/paths")
// get path files
const paths = await getPathsOfTag(tagName, area)
const paths = await getPathsOfTag(tagName, area, version)
return NextResponse.json(
{