docs: add prepare script to generate sidebar (#11894)

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

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

www/apps/api-reference/utils/dereference.ts

@@ -1,19 +1,19 @@
-import { Document, ParsedPathItemObject, SchemaObject } from "@/types/openapi"
+import { OpenAPI } from "types"
 import OpenAPIParser from "@readme/openapi-parser"
 
 type Options = {
   basePath: string
-  paths?: ParsedPathItemObject[]
-  schemas?: SchemaObject[]
+  paths?: OpenAPI.ParsedPathItemObject[]
+  schemas?: OpenAPI.SchemaObject[]
 }
 
 export default async function dereference({
   basePath,
   paths,
   schemas,
-}: Options): Promise<Document> {
+}: Options): Promise<OpenAPI.Document> {
   // dereference the references in the paths
-  let document: Document = {
+  let document: OpenAPI.Document = {
     paths: {},
     // These attributes are only for validation purposes
     openapi: "3.0.0",
@@ -56,7 +56,7 @@ export default async function dereference({
     dereference: {
       circular: "ignore",
     },
-  })) as unknown as Document
+  })) as unknown as OpenAPI.Document
 
   return document
 }

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

@@ -1,28 +1,26 @@
 import path from "path"
 import { promises as fs } from "fs"
-import type { OpenAPIV3 } from "openapi-types"
-import type { Operation, Document, ParsedPathItemObject } from "@/types/openapi"
+import type { OpenAPI } from "types"
 import readSpecDocument from "./read-spec-document"
-import getSectionId from "./get-section-id"
 import dereference from "./dereference"
 import { unstable_cache } from "next/cache"
-import { oasFileToPath } from "docs-utils"
+import { getSectionId, oasFileToPath } from "docs-utils"
 
 async function getPathsOfTag_(
   tagName: string,
   area: string
-): Promise<Document> {
+): Promise<OpenAPI.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(
+  let documents: OpenAPI.ParsedPathItemObject[] = await Promise.all(
     files.map(async (file) => {
       const fileContent = (await readSpecDocument(
         path.join(basePath, file)
-      )) as OpenAPIV3.PathItemObject<Operation>
+      )) as OpenAPI.OpenAPIV3.PathItemObject<OpenAPI.Operation>
 
       return {
         ...fileContent,

www/apps/api-reference/utils/get-schema-content.ts

@@ -1,12 +1,12 @@
 import { promises as fs } from "fs"
 import { parseDocument } from "yaml"
-import { SchemaObject } from "../types/openapi"
+import { OpenAPI } from "types"
 import dereference from "./dereference"
 import { unstable_cache } from "next/cache"
 
 async function getSchemaContent_(schemaPath: string, baseSchemasPath: string) {
   const schemaContent = await fs.readFile(schemaPath, "utf-8")
-  const schema = parseDocument(schemaContent).toJS() as SchemaObject
+  const schema = parseDocument(schemaContent).toJS() as OpenAPI.SchemaObject
 
   // resolve references in schema
   const dereferencedDocument = await dereference({

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

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

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

@@ -1,7 +1,7 @@
-import { OpenAPIV3 } from "openapi-types"
+import { OpenAPI } from "types"
 
 export default function getSecuritySchemaTypeName(
-  securitySchema: OpenAPIV3.SecuritySchemeObject
+  securitySchema: OpenAPI.OpenAPIV3.SecuritySchemeObject
 ) {
   switch (securitySchema.type) {
     case "apiKey":

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

@@ -1,22 +1,21 @@
-import type { Operation, PathsObject } from "@/types/openapi"
-import type { OpenAPIV3 } from "openapi-types"
+import type { OpenAPI } from "types"
 import dynamic from "next/dynamic"
 import type { MethodLabelProps } from "@/components/MethodLabel"
-import getSectionId from "./get-section-id"
 import { Sidebar } from "types"
+import { getSectionId } from "docs-utils"
 
 const MethodLabel = dynamic<MethodLabelProps>(
   async () => import("../components/MethodLabel")
 ) as React.FC<MethodLabelProps>
 
 export default function getTagChildSidebarItems(
-  paths: PathsObject
+  paths: OpenAPI.PathsObject
 ): Sidebar.SidebarItem[] {
   const items: Sidebar.SidebarItem[] = []
   Object.entries(paths).forEach(([, operations]) => {
     Object.entries(operations).map(([method, operation]) => {
-      const definedOperation = operation as Operation
-      const definedMethod = method as OpenAPIV3.HttpMethods
+      const definedOperation = operation as OpenAPI.Operation
+      const definedMethod = method as OpenAPI.OpenAPIV3.HttpMethods
       items.push({
         type: "link",
         path: getSectionId([

www/apps/api-reference/utils/merge-all-of-types.ts

@@ -1,14 +1,14 @@
-import type { PropertiesObject, SchemaObject } from "@/types/openapi"
+import type { OpenAPI } from "types"
 
 export default function mergeAllOfTypes(
-  allOfSchema: SchemaObject
-): SchemaObject {
+  allOfSchema: OpenAPI.SchemaObject
+): OpenAPI.SchemaObject {
   if (!allOfSchema.allOf) {
     // return whatever the schema is
     return allOfSchema
   }
   // merge objects' properties in this var
-  let properties: PropertiesObject = {}
+  let properties: OpenAPI.PropertiesObject = {}
   let foundObjects = false
 
   allOfSchema.allOf.forEach((item) => {

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

@@ -1,8 +1,8 @@
 import { promises as fs } from "fs"
-import { OpenAPIV3 } from "openapi-types"
+import { OpenAPI } from "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
+  return parseDocument(fileContent).toJS() as OpenAPI.OpenAPIV3.PathItemObject
 }