Add pathMetadata

src/data/paths.yaml

@@ -0,0 +1,3 @@
+---
+/acs/systems:
+  description: null

src/lib/blueprint.ts

@@ -13,11 +13,14 @@ export const blueprint = async (
   const codeSampleDefinitions =
     'codeSampleDefinitions' in metadata ? metadata.codeSampleDefinitions : []
 
+  // UPSTREAM: Ideally, path metadata would be unnecessary and contained inside the blueprint.
+  const pathMetadata = 'pathMetadata' in metadata ? metadata.pathMetadata : {}
+
   const typesModule = TypesModuleSchema.parse({
     ...types,
     codeSampleDefinitions,
   })
 
   const blueprint = await createBlueprint(typesModule, { formatCode })
-  Object.assign(metadata, blueprint)
+  Object.assign(metadata, { ...blueprint, pathMetadata })
 }

src/lib/layout-context.ts

@@ -7,6 +7,8 @@ import type {
 } from '@seamapi/blueprint'
 import { pascalCase } from 'change-case'
 
+import type { PathMetadata } from './reference.js'
+
 const supportedSdks: CodeSampleSdk[] = [
   'javascript',
   'python',
@@ -113,6 +115,7 @@ interface ContextResource {
 type ContextEndpoint = Pick<Endpoint, 'path' | 'description'>
 
 export interface RouteLayoutContext {
+  description: string | null
   resources: ContextResource[]
   endpoints: ContextEndpoint[]
 }
@@ -121,7 +124,9 @@ export function setApiRouteLayoutContext(
   file: Partial<RouteLayoutContext>,
   route: Route,
   blueprint: Blueprint,
+  pathMetadata: PathMetadata,
 ): void {
+  file.description = pathMetadata[route.path]?.description ?? null
   file.endpoints = route.endpoints.map(({ path, name, description }) => ({
     path,
     name,

src/lib/reference.ts

@@ -14,18 +14,28 @@ type Metadata = Partial<Pick<Blueprint, 'routes' | 'resources'>>
 
 type File = EndpointLayoutContext & RouteLayoutContext & { layout: string }
 
+export type PathMetadata = Record<
+  string,
+  {
+    description?: string | null
+  }
+>
+
 export const reference = (
   files: Metalsmith.Files,
   metalsmith: Metalsmith,
 ): void => {
-  const metadata = {
+  const { pathMetadata = {}, ...metadata } =
+    metalsmith.metadata() as Metadata & { pathMetadata: PathMetadata }
+
+  const blueprint = {
     title: '',
     routes: [],
     resources: {},
-    ...(metalsmith.metadata() as Metadata),
+    ...metadata,
   }
 
-  for (const route of metadata.routes ?? []) {
+  for (const route of blueprint.routes ?? []) {
     if (route.isUndocumented) continue
 
     if (!route.path.startsWith('/acs/systems')) {
@@ -38,7 +48,7 @@ export const reference = (
     }
     const file = files[k] as unknown as File
     file.layout = 'api-route.hbs'
-    setApiRouteLayoutContext(file, route, metadata)
+    setApiRouteLayoutContext(file, route, blueprint, pathMetadata)
 
     for (const endpoint of route.endpoints) {
       if (endpoint.isUndocumented) continue

src/metalsmith.ts

@@ -25,6 +25,7 @@ Metalsmith(rootDir)
   .use(
     metadata({
       codeSampleDefinitions: './data/code-sample-definitions',
+      pathMetadata: './data/paths.yaml',
     }),
   )
   .use(blueprint)