diff --git a/src/data/paths.yaml b/src/data/paths.yaml new file mode 100644 index 00000000..4569ef27 --- /dev/null +++ b/src/data/paths.yaml @@ -0,0 +1,3 @@ +--- +/acs/systems: + description: null diff --git a/src/lib/blueprint.ts b/src/lib/blueprint.ts index ea63b300..f0f1fcba 100644 --- a/src/lib/blueprint.ts +++ b/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 }) } diff --git a/src/lib/layout-context.ts b/src/lib/layout-context.ts index 01efb67a..d355ffcd 100644 --- a/src/lib/layout-context.ts +++ b/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 export interface RouteLayoutContext { + description: string | null resources: ContextResource[] endpoints: ContextEndpoint[] } @@ -121,7 +124,9 @@ export function setApiRouteLayoutContext( file: Partial, route: Route, blueprint: Blueprint, + pathMetadata: PathMetadata, ): void { + file.description = pathMetadata[route.path]?.description ?? null file.endpoints = route.endpoints.map(({ path, name, description }) => ({ path, name, diff --git a/src/lib/reference.ts b/src/lib/reference.ts index 991d3252..97038023 100644 --- a/src/lib/reference.ts +++ b/src/lib/reference.ts @@ -14,18 +14,28 @@ type Metadata = Partial> 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 diff --git a/src/metalsmith.ts b/src/metalsmith.ts index 8883f81b..c389b013 100644 --- a/src/metalsmith.ts +++ b/src/metalsmith.ts @@ -25,6 +25,7 @@ Metalsmith(rootDir) .use( metadata({ codeSampleDefinitions: './data/code-sample-definitions', + pathMetadata: './data/paths.yaml', }), ) .use(blueprint)