Path browsers in the document viewer

Apicurio · Nov 21, 2024 · ef91fa3 · ef91fa3
1 parent 261706b
commit ef91fa3
Show file tree

Hide file tree

Showing 13 changed files with 324 additions and 44 deletions.
diff --git a/packages/ui/package.json b/packages/ui/package.json
@@ -33,6 +33,7 @@
     "@patternfly/react-icons": "^6.0.0",
     "@patternfly/react-table": "^6.0.0",
     "@statelyai/inspect": "^0.4.0",
+    "@total-typescript/ts-reset": "^0.6.1",
     "@types/lodash": "^4",
     "@types/react": "^18.3.3",
     "@types/react-dom": "^18.3.0",

diff --git a/packages/ui/src/OpenApiEditor.tsx b/packages/ui/src/OpenApiEditor.tsx
@@ -14,11 +14,11 @@ import { fromPromise } from "xstate";
 import { EditorSidebar } from "./components/EditorSidebar";
 import { OpenApiEditorMachine } from "./OpenApiEditorMachine.ts";
 import {
+  Document,
   DocumentDataType,
   DocumentNavigation,
   DocumentPath,
   DocumentResponse,
-  DocumentRoot,
   EditorModel,
   NodeDataType,
   NodePath,
@@ -68,7 +68,7 @@ export type OpenApiEditorProps = {
   spec: string;
   parseOpenApi: (document: string) => Promise<void>;
   getEditorState: (filter: string) => Promise<EditorModel>;
-  getDocumentRootSnapshot: () => Promise<DocumentRoot>;
+  getDocumentSnapshot: () => Promise<Document>;
   getPathSnapshot: (path: NodePath) => Promise<DocumentPath>;
   getDataTypeSnapshot: (path: NodeDataType) => Promise<DocumentDataType>;
   getResponseSnapshot: (path: NodeResponse) => Promise<DocumentResponse>;
@@ -104,7 +104,7 @@ export const OpenApiEditor = forwardRef<OpenApiEditorRef, OpenApiEditorProps>(
       spec,
       parseOpenApi,
       getEditorState,
-      getDocumentRootSnapshot,
+      getDocumentSnapshot,
       getPathSnapshot,
       getDataTypeSnapshot,
       getResponseSnapshot,
@@ -137,7 +137,7 @@ export const OpenApiEditor = forwardRef<OpenApiEditorRef, OpenApiEditorProps>(
 
     const documentRootDesigner = DocumentDesignerMachine.provide({
       actors: {
-        getDocumentRootSnapshot: fromPromise(() => getDocumentRootSnapshot()),
+        getDocumentSnapshot: fromPromise(() => getDocumentSnapshot()),
         updateDocumentTitle: fromPromise(({ input }) =>
           updateDocumentTitle(input)
         ),

diff --git a/packages/ui/src/OpenApiEditorMachine.ts b/packages/ui/src/OpenApiEditorMachine.ts
@@ -258,7 +258,7 @@ export const OpenApiEditorMachine = setup({
                   return spawn("pathDesigner", {
                     input: {
                       parentRef: self,
-                      path: context.selectedNode,
+                      node: context.selectedNode,
                       editable: context.view === "design",
                     },
                   });

diff --git a/packages/ui/src/OpenApiEditorModels.ts b/packages/ui/src/OpenApiEditorModels.ts
@@ -39,13 +39,23 @@ export type Operation = {
 };
 
 export type DocumentPath = {
+  node: NodePath;
   summary: string;
   description: string;
   servers: Server[];
   queryParameters: "TODO";
   headerParameters: "TODO";
   cookieParameters: "TODO";
-  operations: Operation[];
+  operations: {
+    get?: Operation;
+    put?: Operation;
+    post?: Operation;
+    delete?: Operation;
+    options?: Operation;
+    head?: Operation;
+    patch?: Operation;
+    trace?: Operation;
+  };
 };
 
 export type DataTypeProperty = {
@@ -83,7 +93,7 @@ export type SecurityRequirement = {
   schemes: string[];
 };
 
-export type DocumentRoot = {
+export type Document = {
   title: string;
   version: string;
   description: string;
@@ -96,6 +106,7 @@ export type DocumentRoot = {
   servers: Server[];
   securityScheme: SecurityScheme[];
   securityRequirements: SecurityRequirement[];
+  paths: DocumentPath[];
 };
 
 export type NodeRoot = {

diff --git a/packages/ui/src/OpenApiEditorWorker.ts b/packages/ui/src/OpenApiEditorWorker.ts
@@ -6,11 +6,11 @@ import YAML from "yaml";
 
 import {
   DataTypeProperty,
+  Document,
   DocumentDataType,
   DocumentNavigation,
   DocumentPath,
   DocumentResponse,
-  DocumentRoot,
   EditorModel,
   NavigationDataType,
   NavigationPath,
@@ -205,16 +205,48 @@ export async function parseOpenApi(schema: string) {
   }
 }
 
-export async function getPathSnapshot(node: NodePath): Promise<DocumentPath> {
-  const path = resolveNode(node.nodePath);
+function oasOperationToOperation(
+  operation?: DM.Operation
+): Operation | undefined {
+  if (operation) {
+    return {
+      summary: operation.summary,
+      description: operation.description,
+      id: operation.operationId,
+      tags: [],
+      servers: [],
+      queryParameters: "TODO",
+      headerParameters: "TODO",
+      cookieParameters: "TODO",
+      requestBody: undefined,
+      responses: [],
+      securityRequirements: [],
+    };
+  }
+}
 
+function oasNodeToPath(_path: DM.Node): DocumentPath {
   if (document.is3xDocument()) {
-    const pathOas30 = path as DM.Oas30PathItem;
-    const summary = pathOas30.summary;
-    const description = pathOas30.description;
+    const path = _path as DM.Oas30PathItem;
+    const summary = path.summary;
+    const description = path.description;
     const servers: Server[] = [];
-    const operations: Operation[] = [];
+    const operations = {
+      get: oasOperationToOperation(path.get),
+      put: oasOperationToOperation(path.put),
+      post: oasOperationToOperation(path.post),
+      delete: oasOperationToOperation(path.delete),
+      options: oasOperationToOperation(path.options),
+      head: oasOperationToOperation(path.head),
+      patch: oasOperationToOperation(path.patch),
+      trace: oasOperationToOperation(path["trace"]),
+    };
     return {
+      node: {
+        type: "path",
+        path: path.getPath(),
+        nodePath: DM.Library.createNodePath(_path).toString(),
+      },
       summary,
       description,
       servers,
@@ -224,18 +256,39 @@ export async function getPathSnapshot(node: NodePath): Promise<DocumentPath> {
       cookieParameters: "TODO",
     };
   } else {
+    const path = _path as DM.Oas20PathItem;
+    const operations = {
+      get: oasOperationToOperation(path.get),
+      put: oasOperationToOperation(path.put),
+      post: oasOperationToOperation(path.post),
+      delete: oasOperationToOperation(path.delete),
+      options: oasOperationToOperation(path.options),
+      head: oasOperationToOperation(path.head),
+      patch: oasOperationToOperation(path.patch),
+      trace: undefined,
+    };
     return {
+      node: {
+        type: "path",
+        path: path.getPath(),
+        nodePath: DM.Library.createNodePath(_path).toString(),
+      },
       summary: "",
       description: "",
       servers: [],
-      operations: [],
+      operations,
       queryParameters: "TODO",
       headerParameters: "TODO",
       cookieParameters: "TODO",
     };
   }
 }
 
+export async function getPathSnapshot(node: NodePath): Promise<DocumentPath> {
+  const path = resolveNode(node.nodePath);
+  return oasNodeToPath(path);
+}
+
 export async function getDataTypeSnapshot(
   node: NodeDataType
 ): Promise<DocumentDataType> {
@@ -315,8 +368,8 @@ export async function getResponseSnapshot(
   }
 }
 
-export async function getDocumentRootSnapshot(): Promise<DocumentRoot> {
-  console.log("getDocumentRootSnapshot");
+export async function getDocumentSnapshot(): Promise<Document> {
+  console.log("getDocumentSnapshot");
   return {
     title: document.info.title,
     version: document.info.version,
@@ -345,6 +398,7 @@ export async function getDocumentRootSnapshot(): Promise<DocumentRoot> {
       document.security?.map((s) => ({
         schemes: s.getSecurityRequirementNames() ?? [],
       })) ?? [],
+    paths: getOasPaths().map(oasNodeToPath),
   };
 }
 

diff --git a/packages/ui/src/components/Toc.tsx b/packages/ui/src/components/Toc.tsx
@@ -6,7 +6,7 @@ export function Toc({ children }: PropsWithChildren) {
   return (
     <JumpLinks
       className={classes.toc}
-      scrollableSelector={".apicurio-editor .pf-v6-c-drawer__panel-main"}
+      scrollableSelector={".apicurio-editor .pf-v6-c-drawer__content"}
       isVertical={true}
       expandable={{ default: "expandable", lg: "nonExpandable" }}
       label={"Table of contents"}

diff --git a/packages/ui/src/documentDesigner/Designer.tsx b/packages/ui/src/documentDesigner/Designer.tsx
@@ -7,24 +7,29 @@ import { SecurityScheme } from "./SecurityScheme.tsx";
 import { SecurityRequirements } from "./SecurityRequirements.tsx";
 import { useMachineSelector } from "./DocumentDesignerMachineContext.ts";
 import { DesignerLayout } from "./DesignerLayout.tsx";
+import { Paths } from "./Paths.tsx";
 
 export function Designer() {
   const {
     tagDefinitionsCount,
     serversCount,
     securitySchemeCount,
     securityRequirementsCount,
+    pathsCount,
   } = useMachineSelector(({ context }) => {
     return {
       tagDefinitionsCount: context.tags?.length,
       serversCount: context.servers?.length,
       securitySchemeCount: context.securityScheme?.length,
       securityRequirementsCount: context.securityRequirements?.length,
+      pathsCount: context.paths?.length,
     };
   });
   return (
     <DesignerLayout
       info={<Info />}
+      paths={<Paths />}
+      pathsCount={pathsCount}
       contact={<Contact />}
       license={<License />}
       tagDefinitions={<TagDefinitions />}

diff --git a/packages/ui/src/documentDesigner/DesignerLayout.tsx b/packages/ui/src/documentDesigner/DesignerLayout.tsx
@@ -3,38 +3,44 @@ import { Toc } from "../components/Toc.tsx";
 import { TocContainer } from "../components/TocContainer.tsx";
 import { Section } from "../components/Section.tsx";
 import { ReactNode } from "react";
+import { SectionSkeleton } from "../components/SectionSkeleton.tsx";
 
 export function DesignerLayout({
-  info,
-  contact,
-  license,
+  info = <SectionSkeleton />,
+  paths = <SectionSkeleton />,
+  contact = <SectionSkeleton />,
+  license = <SectionSkeleton />,
+  tagDefinitions = <SectionSkeleton />,
+  servers = <SectionSkeleton />,
+  securityScheme = <SectionSkeleton />,
+  securityRequirements = <SectionSkeleton />,
+  pathsCount,
   tagDefinitionsCount,
-  tagDefinitions,
   serversCount,
-  servers,
   securitySchemeCount,
-  securityScheme,
   securityRequirementsCount,
-  securityRequirements,
 }: {
-  info: ReactNode;
-  contact: ReactNode;
-  license: ReactNode;
+  info?: ReactNode;
+  paths?: ReactNode;
+  contact?: ReactNode;
+  license?: ReactNode;
+  tagDefinitions?: ReactNode;
+  servers?: ReactNode;
+  securityScheme?: ReactNode;
+  securityRequirements?: ReactNode;
+  pathsCount?: number;
   tagDefinitionsCount?: number;
-  tagDefinitions: ReactNode;
   serversCount?: number;
-  servers: ReactNode;
   securitySchemeCount?: number;
-  securityScheme: ReactNode;
   securityRequirementsCount?: number;
-  securityRequirements: ReactNode;
 }) {
   return (
     <Flex>
       <Toc>
         <JumpLinksItem href="#info">Info</JumpLinksItem>
         <JumpLinksItem href="#contact">Contact</JumpLinksItem>
         <JumpLinksItem href="#license">License</JumpLinksItem>
+        <JumpLinksItem href="#paths">Paths</JumpLinksItem>
         <JumpLinksItem href="#tag-definitions">Tag definitions</JumpLinksItem>
         <JumpLinksItem href="#servers">Servers</JumpLinksItem>
         <JumpLinksItem href="#security-scheme">Security scheme</JumpLinksItem>
@@ -55,6 +61,10 @@ export function DesignerLayout({
           {license}
         </Section>
         <Divider inset={{ default: "insetNone" }} />
+        <Section title={"Paths"} id={"paths"} count={pathsCount}>
+          {paths}
+        </Section>
+        <Divider inset={{ default: "insetNone" }} />
         <Section
           title={"Tag definitions"}
           count={tagDefinitionsCount}

diff --git a/packages/ui/src/documentDesigner/DocumentDesignerMachine.ts b/packages/ui/src/documentDesigner/DocumentDesignerMachine.ts
@@ -1,7 +1,7 @@
 import { ActorRef, assign, fromPromise, sendTo, setup, Snapshot } from "xstate";
-import { DocumentRoot } from "../OpenApiEditorModels";
+import { Document } from "../OpenApiEditorModels";
 
-type Context = DocumentRoot & {
+type Context = Document & {
   parentRef: ParentActor;
   editable: boolean;
 };
@@ -50,8 +50,8 @@ export const DocumentDesignerMachine = setup({
     },
   },
   actors: {
-    getDocumentRootSnapshot: fromPromise<DocumentRoot, void>(() =>
-      Promise.resolve({} as DocumentRoot)
+    getDocumentSnapshot: fromPromise<Document, void>(() =>
+      Promise.resolve({} as Document)
     ),
     updateDocumentTitle: fromPromise<void, string>(() => Promise.resolve()),
     updateDocumentVersion: fromPromise<void, string>(() => Promise.resolve()),
@@ -70,7 +70,7 @@ export const DocumentDesignerMachine = setup({
   },
   actions: {},
 }).createMachine({
-  id: "documentRootDesigner",
+  id: "documentDesigner",
   context: ({ input }) => {
     return {
       ...input,
@@ -80,7 +80,7 @@ export const DocumentDesignerMachine = setup({
   states: {
     loading: {
       invoke: {
-        src: "getDocumentRootSnapshot",
+        src: "getDocumentSnapshot",
         onDone: {
           target: "idle",
           actions: assign(({ event }) => event.output),
@@ -90,7 +90,7 @@ export const DocumentDesignerMachine = setup({
     },
     idle: {
       invoke: {
-        src: "getDocumentRootSnapshot",
+        src: "getDocumentSnapshot",
         onDone: {
           actions: assign(({ event }) => event.output),
         },