chore: minor fixes and linking

Author: cjbell

components/ApiReference/ApiReferenceContext.tsx

@@ -1,11 +1,14 @@
 import { createContext, useContext, ReactNode } from "react";
 import { OpenAPIV3 } from "@scalar/openapi-types";
 import { StainlessConfig } from "../../lib/openApiSpec";
+import { buildSchemaReferences } from "./helpers";
+import { useRouter } from "next/router";
 
 interface ApiReferenceContextType {
   openApiSpec: OpenAPIV3.Document;
   stainlessConfig: StainlessConfig;
   baseUrl: string;
+  schemaReferences: Record<string, string>;
 }
 
 const ApiReferenceContext = createContext<ApiReferenceContextType | undefined>(
@@ -23,11 +26,20 @@ export function ApiReferenceProvider({
   openApiSpec,
   stainlessConfig,
 }: ApiReferenceProviderProps) {
+  const router = useRouter();
+  const basePath = router.pathname.split("/")[1];
+
   const baseUrl = stainlessConfig.environments.production;
+  const schemaReferences = buildSchemaReferences(
+    openApiSpec,
+    stainlessConfig,
+    Object.keys(stainlessConfig.resources),
+    `/${basePath}`,
+  );
 
   return (
     <ApiReferenceContext.Provider
-      value={{ openApiSpec, stainlessConfig, baseUrl }}
+      value={{ openApiSpec, stainlessConfig, baseUrl, schemaReferences }}
     >
       {children}
     </ApiReferenceContext.Provider>

components/ApiReference/ApiReferenceMethod/ApiReferenceMethod.tsx

@@ -11,6 +11,7 @@ import OperationParameters from "../OperationParameters/OperationParameters";
 import { PropertyRow } from "../SchemaProperties/PropertyRow";
 import MultiLangExample from "../MultiLangExample";
 import { augmentSnippetsWithCurlRequest } from "../helpers";
+import Link from "next/link";
 
 type Props = {
   methodName: string;
@@ -19,7 +20,7 @@ type Props = {
 };
 
 function ApiReferenceMethod({ methodName, methodType, endpoint }: Props) {
-  const { openApiSpec, baseUrl } = useApiReference();
+  const { openApiSpec, baseUrl, schemaReferences } = useApiReference();
   const [isResponseExpanded, setIsResponseExpanded] = useState(false);
   const method = openApiSpec.paths?.[endpoint]?.[methodType];
 
@@ -52,7 +53,7 @@ function ApiReferenceMethod({ methodName, methodType, endpoint }: Props) {
 
         <Endpoint
           method={methodType.toUpperCase()}
-          path={`${baseUrl}${endpoint}`}
+          path={`${endpoint}`}
           name={methodName}
         />
 
@@ -83,7 +84,11 @@ function ApiReferenceMethod({ methodName, methodType, endpoint }: Props) {
           <PropertyRow.Wrapper>
             <PropertyRow.Container>
               <PropertyRow.Header>
-                <PropertyRow.Type>{responseSchema.title}</PropertyRow.Type>
+                <PropertyRow.Type
+                  href={schemaReferences[responseSchema.title ?? ""]}
+                >
+                  {responseSchema.title}
+                </PropertyRow.Type>
               </PropertyRow.Header>
               <PropertyRow.Description>
                 <Markdown>{responseSchema.description ?? ""}</Markdown>

components/ApiReference/ApiReferenceSection/ApiReferenceSection.tsx

@@ -76,6 +76,19 @@ function ApiReferenceSection({ resourceName, resource, path }: Props) {
         );
       })}
 
+      {Object.entries(resource.subresources ?? {}).map(
+        ([subresourceName, subresource]) => {
+          return (
+            <ApiReferenceSection
+              key={subresourceName}
+              resourceName={subresourceName}
+              resource={subresource}
+              path={`${basePath}/${subresourceName}`}
+            />
+          );
+        },
+      )}
+
       {Object.entries(models).map(([modelName, modelReference]) => {
         const schema: OpenAPIV3.SchemaObject | undefined = JSONPointer.get(
           openApiSpec,
@@ -113,19 +126,6 @@ function ApiReferenceSection({ resourceName, resource, path }: Props) {
           </div>
         );
       })}
-
-      {Object.entries(resource.subresources ?? {}).map(
-        ([subresourceName, subresource]) => {
-          return (
-            <ApiReferenceSection
-              key={subresourceName}
-              resourceName={subresourceName}
-              resource={subresource}
-              path={`${basePath}/${subresourceName}`}
-            />
-          );
-        },
-      )}
     </>
   );
 }

components/ApiReference/SchemaProperties/PropertyRow.tsx

@@ -1,4 +1,5 @@
 import classNames from "classnames";
+import Link from "next/link";
 import { IoChevronDown } from "react-icons/io5";
 
 const Header = ({ children }) => (
@@ -29,11 +30,30 @@ const Types = ({ children }) => (
   </div>
 );
 
-const Type = ({ children }) => (
-  <span className="font-mono text-xs px-1 bg-gray-50 dark:bg-gray-800 border border-gray-100 dark:border-gray-700 rounded-md">
-    {children}
-  </span>
-);
+const Type = ({
+  children,
+  href,
+}: {
+  children: React.ReactNode;
+  href?: string;
+}) => {
+  if (href) {
+    return (
+      <Link
+        href={href}
+        className="font-mono text-xs px-1 bg-gray-50 dark:bg-gray-800 border border-gray-100 dark:border-gray-700 rounded-md !no-underline"
+      >
+        {children}
+      </Link>
+    );
+  }
+
+  return (
+    <span className="font-mono text-xs px-1 bg-gray-50 dark:bg-gray-800 border border-gray-100 dark:border-gray-700 rounded-md">
+      {children}
+    </span>
+  );
+};
 
 const Description = ({ children }) => (
   <div className="text-sm text-gray-500 dark:text-gray-300 schema-property-description">

components/ApiReference/SchemaProperties/SchemaProperty.tsx

@@ -9,6 +9,7 @@ import {
   maybeFlattenUnionSchema,
   resolveChildProperties,
 } from "./helpers";
+import { useApiReference } from "../ApiReferenceContext";
 
 type Props = {
   name?: string;
@@ -18,6 +19,7 @@ type Props = {
 const MAX_TYPES_TO_DISPLAY = 2;
 
 const SchemaProperty = ({ name, schema }: Props) => {
+  const { schemaReferences } = useApiReference();
   const [isPossibleTypesOpen, setIsPossibleTypesOpen] = useState(false);
   const [isChildPropertiesOpen, setIsChildPropertiesOpen] = useState(false);
   // If the schema is an array, then we want to show the possible types that the array can contain.
@@ -35,7 +37,9 @@ const SchemaProperty = ({ name, schema }: Props) => {
         {name && <PropertyRow.Name>{name}</PropertyRow.Name>}
         <PropertyRow.Types>
           {typesForDisplay.slice(0, MAX_TYPES_TO_DISPLAY).map((type) => (
-            <PropertyRow.Type key={type}>{type}</PropertyRow.Type>
+            <PropertyRow.Type key={type} href={schemaReferences[type]}>
+              {type}
+            </PropertyRow.Type>
           ))}
           {hasAdditionalTypes && (
             <span className="text-xs text-gray-500 dark:text-gray-300">

components/ApiReference/helpers.ts

@@ -15,6 +15,76 @@ function resolveEndpointFromMethod(
   return [methodType, endpoint];
 }
 
+function buildSchemaReferencesForResource(
+  resource: StainlessResource,
+  openApiSpec: OpenAPIV3.Document,
+  basePath: string,
+) {
+  const schemaReferences: Record<string, string> = {};
+
+  if (resource.models) {
+    Object.entries(resource.models).forEach(([modelName, modelRef]) => {
+      const schema: OpenAPIV3.SchemaObject | undefined = JSONPointer.get(
+        openApiSpec,
+        modelRef.replace("#", ""),
+      );
+
+      const title = schema?.title ?? modelName;
+
+      if (schema) {
+        schemaReferences[title] = `${basePath}/schemas/${modelName}`;
+        // This is a hack to make lists work without doing anything to the inner type behavior
+        schemaReferences[`${title}[]`] = `${basePath}/schemas/${modelName}`;
+      }
+    });
+  }
+
+  if (resource.subresources) {
+    Object.entries(resource.subresources).forEach(
+      ([subresourceName, subresource]) => {
+        Object.assign(
+          schemaReferences,
+          buildSchemaReferencesForResource(
+            subresource,
+            openApiSpec,
+            `${basePath}/${subresourceName}`,
+          ),
+        );
+      },
+    );
+  }
+
+  return schemaReferences;
+}
+
+/**
+ * Given a spec and config, builds a complete list of all of the schemas referenced
+ * as a map for easy lookup from SchemaName -> path. We use this to then link to schemas
+ */
+function buildSchemaReferences(
+  openApiSpec: OpenAPIV3.Document,
+  stainlessSpec: StainlessConfig,
+  resourceOrder: string[],
+  basePath: string,
+) {
+  const schemaReferences: Record<string, string> = {};
+
+  resourceOrder.forEach((resourceName) => {
+    const resource = stainlessSpec.resources[resourceName];
+
+    Object.assign(
+      schemaReferences,
+      buildSchemaReferencesForResource(
+        resource,
+        openApiSpec,
+        `${basePath}/${resourceName}`,
+      ),
+    );
+  });
+
+  return schemaReferences;
+}
+
 function getSidebarContent(
   openApiSpec: OpenAPIV3.Document,
   stainlessSpec: StainlessConfig,
@@ -60,6 +130,20 @@ function buildSidebarPages(
     );
   }
 
+  if (resource.subresources) {
+    pages.push(
+      ...Object.entries(resource.subresources).map(
+        ([subresourceName, subresource]) => {
+          return {
+            title: subresource.name || subresourceName,
+            slug: `/${subresourceName}`,
+            pages: buildSidebarPages(subresource, openApiSpec),
+          };
+        },
+      ),
+    );
+  }
+
   if (resource.models) {
     pages.push({
       title: "Object definitions",
@@ -78,20 +162,6 @@ function buildSidebarPages(
     });
   }
 
-  if (resource.subresources) {
-    pages.push(
-      ...Object.entries(resource.subresources).map(
-        ([subresourceName, subresource]) => {
-          return {
-            title: subresource.name || subresourceName,
-            slug: `/${subresourceName}`,
-            pages: buildSidebarPages(subresource, openApiSpec),
-          };
-        },
-      ),
-    );
-  }
-
   return pages;
 }
 
@@ -127,4 +197,5 @@ export {
   resolveEndpointFromMethod,
   buildSidebarPages,
   augmentSnippetsWithCurlRequest,
+  buildSchemaReferences,
 };