galbe 0.15.6 → 0.16.0

package/src/extras/spec/openapi.serializer.ts

@@ -12,10 +12,17 @@ import type {
 } from '../../../src/schema'
 
 import { Galbe } from '../../../src'
-import { walkRoutes, HttpStatus } from '../../../src/util'
+import {
+  walkRoutes,
+  HttpStatus,
+  matchMiddleware,
+  parseMiddlewarePattern,
+  routeHead,
+  RESPONSE_RANGE_DESCRIPTION,
+} from '../../../src/util'
 import { Kind, Optional } from '../../../src/schema'
 
-import { OpenAPIV3 } from 'openapi-types'
+import type { OpenAPIV3 } from 'openapi-types'
 
 type SchemaType = { type: string; format: string; isJson: boolean }
 
@@ -28,15 +35,56 @@ const schemaToMedia = ({ type, format, isJson }: SchemaType, hasComposite = fals
         ? 'text/plain'
         : 'application/json'
 
+/**
+ * `{type, enum}` for a set of literals that share one primitive type — the
+ * idiomatic OpenAPI spelling for both a lone literal and a union of them.
+ * `STLiteral` accepts `string | number | boolean`, so the type is read off the
+ * value rather than assumed to be `string`. Returns null for a mixed-type set,
+ * which has to stay in its `anyOf`/`oneOf` form.
+ */
+const literalEnum = (members: STSchema[]): { type: string; enum: any[] } | null => {
+  if (!members.length || !members.every(m => m[Kind] === 'literal')) return null
+  const values = members.map(m => (m as STLiteral).value)
+  const types = new Set(values.map(v => typeof v))
+  if (types.size !== 1) return null
+  switch ([...types][0]) {
+    case 'string':
+      return { type: 'string', enum: values }
+    case 'boolean':
+      return { type: 'boolean', enum: values }
+    case 'number':
+      return { type: values.every(v => Number.isInteger(v)) ? 'integer' : 'number', enum: values }
+    default:
+      return null
+  }
+}
+
 export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<OpenAPIV3.Document> => {
+  // OpenAPI 3.0 schemas follow JSON Schema draft-4, where `exclusiveMinimum` /
+  // `exclusiveMaximum` are booleans modifying `minimum` / `maximum`. 3.1 (JSON
+  // Schema 2020-12) makes them the numeric bound itself.
+  const draft4Bounds = version.startsWith('3.0')
   let paths: any = {}
   let components: OpenAPIV3.ComponentsObject = {
-    securitySchemes: {},
+    securitySchemes: { ...g.config?.openapi?.securitySchemes },
     schemas: {},
     parameters: {},
     requestBodies: {},
     responses: {},
   }
+  // A scheme the app declared is authoritative: a middleware def may not
+  // redefine a name the config already owns.
+  const declaredSchemes = new Set(Object.keys(g.config?.openapi?.securitySchemes ?? {}))
+
+  // A middleware def may define the scheme it enforces, not just name it: an
+  // `apiKey` or `basic` middleware is not expressible as a name alone.
+  for (const m of g.middlewares) {
+    for (const [name, scheme] of Object.entries(m.securitySchemes ?? {})) {
+      if (declaredSchemes.has(name)) continue
+      components.securitySchemes![name] = scheme
+      declaredSchemes.add(name)
+    }
+  }
 
   const schemaToOpenapi = (
     schema: STSchema
@@ -58,12 +106,34 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
     else if (kind === 'byteArray') s = { type: 'string', format: 'binary' }
     else if (kind === 'number' || kind === 'integer') {
       const n = schema as STNumber | STInteger
+      // An exclusive bound wins over an inclusive one on the same side: draft-4
+      // has a single `minimum`/`maximum` slot, and the exclusive form is the
+      // one the parser emits when the source spec marked the bound exclusive.
+      const lower =
+        n.exclusiveMin !== undefined
+          ? { value: n.exclusiveMin, exclusive: true }
+          : n.min !== undefined
+            ? { value: n.min, exclusive: false }
+            : undefined
+      const upper =
+        n.exclusiveMax !== undefined
+          ? { value: n.exclusiveMax, exclusive: true }
+          : n.max !== undefined
+            ? { value: n.max, exclusive: false }
+            : undefined
+      const bound = (b: typeof lower, key: 'minimum' | 'maximum') => {
+        if (!b) return {}
+        if (!b.exclusive) return { [key]: b.value }
+        return draft4Bounds
+          ? { [key]: b.value, [`exclusive${key[0]!.toUpperCase()}${key.slice(1)}`]: true }
+          : { [`exclusive${key[0]!.toUpperCase()}${key.slice(1)}`]: b.value }
+      }
       s = {
         type: kind,
-        ...(n.exclusiveMin !== undefined ? { exclusiveMinimum: n.exclusiveMin } : {}),
-        ...(n.exclusiveMax !== undefined ? { exclusiveMaximum: n.exclusiveMax } : {}),
-        ...(n.min !== undefined ? { minimum: n.min } : {}),
-        ...(n.max !== undefined ? { maximum: n.max } : {}),
+        ...(n.format ? { format: n.format } : {}),
+        ...bound(lower, 'minimum'),
+        ...bound(upper, 'maximum'),
+        ...(n.multipleOf !== undefined ? { multipleOf: n.multipleOf } : {}),
       }
     } else if (kind === 'string') {
       const str = schema as STString
@@ -78,8 +148,7 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
       }
     } else if (kind === 'any') s = {}
     else if (kind === 'literal') {
-      let value = (schema as STLiteral).value
-      s = { type: 'string', enum: [value] }
+      s = literalEnum([schema]) ?? {}
     } else if (kind === 'array') {
       const arr = schema as STArray
       // ArrayOptions exposes minLength/maxLength (matching the schema-builder API);
@@ -96,10 +165,17 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
       let required = Object.entries(props)
         .filter(([_, v]) => !v?.[Optional])
         .map(([k, _]) => k)
+      // `$T.object()` with no props means "any object"; `properties: {}` reads
+      // to most tooling as "an object with no known properties" instead, so an
+      // empty map is omitted rather than emitted.
+      const ap = (schema as STObject).additionalProperties
       s = {
         type: 'object',
-        properties: Object.fromEntries(Object.entries(props).map(([k, v]) => [k, schemaToOpenapi(v).schema])),
+        ...(Object.keys(props).length
+          ? { properties: Object.fromEntries(Object.entries(props).map(([k, v]) => [k, schemaToOpenapi(v).schema])) }
+          : {}),
         ...(required.length ? { required } : {}),
+        ...(ap === undefined ? {} : { additionalProperties: ap === false ? false : schemaToOpenapi(ap).schema }),
       }
     } else if (kind === 'json') {
       const inner = (schema as STJson).value as STSchema | undefined
@@ -110,16 +186,18 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
       let nullable = members.some(s => s[Kind] === 'null')
       members = members.filter(s => s[Kind] !== 'null')
 
-      const allStringLiterals =
-        members.length > 0 && members.every(e => e[Kind] === 'literal' && typeof (e as STLiteral).value === 'string')
       const useOneOf = kind === 'oneOf'
+      // `oneOf` keeps its explicit form — the author asked for "exactly one of
+      // these", and an `enum` does not say that. `anyOf` over literals is just
+      // a closed value set, which is what `enum` means.
+      const asEnum = useOneOf ? null : literalEnum(members)
 
       if (members.length === 0) {
         s = {}
       } else if (members.length === 1) {
         s = schemaToOpenapi(members[0]!).schema
-      } else if (allStringLiterals && !useOneOf) {
-        s = { type: 'string', enum: members.map(e => (e as STLiteral).value) }
+      } else if (asEnum) {
+        s = asEnum
       } else if (members.length > 1) {
         const variants = members.map(e => schemaToOpenapi(e).schema)
         s = useOneOf ? { oneOf: variants } : { anyOf: variants }
@@ -146,6 +224,9 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
       ...s,
       ...(schema?.default !== undefined ? { default: schema.default } : {}),
       ...(schema?.examples !== undefined ? { example: schema.examples } : {}),
+      // documentation-only access annotations, valid on any schema
+      ...(schema?.readOnly ? { readOnly: true } : {}),
+      ...(schema?.writeOnly ? { writeOnly: true } : {}),
     }
     if (components.schemas && schema.id) {
       components.schemas[schema.id] = s
@@ -167,39 +248,105 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
     }, components[kind])
   }
 
+  /**
+   * The `style`/`explode` pair, emitted only where Galbe's parser does something
+   * other than the OpenAPI default. A query array accepts both the repeated and
+   * the comma form, which is the default pair — nothing to say. A custom
+   * `split` is `pipeDelimited`/`spaceDelimited`, and an object query parameter
+   * is `deepObject`, both of which the parser implements.
+   */
+  const paramSerialization = (param: STSchema, kind: 'query' | 'header' | 'path' | 'cookie') => {
+    if (kind !== 'query') return {}
+    if (param[Kind] === 'object') return { style: 'deepObject', explode: true }
+    if (param[Kind] === 'array') {
+      const split = (param as STArray).split
+      if (split === '|') return { style: 'pipeDelimited' }
+      if (split === ' ') return { style: 'spaceDelimited' }
+    }
+    return {}
+  }
+
   const parseParam = (key: string, param: STSchema, kind: 'query' | 'header' | 'path' | 'cookie') => {
     let { schema } = schemaToOpenapi({ ...param, [Optional]: false })
+    // A Galbe schema has one `description`, which is where a parameter's own
+    // description lives. It belongs on the Parameter Object, so lift it and
+    // drop the copy the schema serializer emitted (same as response headers).
+    if ((schema as any)?.description) delete (schema as any).description
     let p: OpenAPIV3.ParameterObject = {
       name: key,
       in: kind,
       description: param?.description,
       required: kind === 'path' ? true : !param[Optional] || undefined,
       deprecated: param.deprecated,
+      ...paramSerialization(param, kind),
       schema,
     }
     return p
   }
 
-  const metaRoutes = g.meta?.reduce(
-    (routes, c) => ({ ...routes, ...c.routes }),
-    {} as Record<string, Record<string, Record<string, any>>>
-  )
-  let metaStatic = Object.fromEntries(Object.entries(metaRoutes || {}).filter(([_, d]) => d?.static))
+  const metaRoutes: Record<string, Record<string, Record<string, any>>> = {}
+  // A route file's own header meta applies to every route the file declares —
+  // the same contract a middleware file's header has over its scope. Kept
+  // beside the route meta rather than merged into it so route-level metadata
+  // can still win.
+  const metaFileHeaders: Record<string, Record<string, any>> = {}
+  for (const c of g.meta ?? []) {
+    for (const [routePath, methods] of Object.entries(c.routes ?? {})) {
+      metaRoutes[routePath] = { ...metaRoutes[routePath], ...methods }
+      if (c.header && Object.keys(c.header).length) metaFileHeaders[routePath] = c.header
+    }
+  }
+  let metaStatic = Object.fromEntries(Object.entries(metaRoutes).filter(([_, d]) => d?.static))
+
+  // middleware-file header meta applies to every operation in the file's scope
+  const mwMeta = (g.metaMiddleware ?? [])
+    .filter(m => m.header && Object.keys(m.header).length)
+    .map(m => ({ segments: parseMiddlewarePattern(m.scope), header: m.header }))
+
+  // Middleware-scope security, from both ways a middleware can carry it: a
+  // middleware file's `@security` header and a def's `security` field. One rung
+  // of the precedence chain, so a packaged middleware documents itself the same
+  // whether it was registered in code or discovered as a file.
+  const hasSecurity = (s: unknown) => s !== undefined && !(Array.isArray(s) && !s.length)
+  // Nearest scope wins: a longer pattern is more specific, and an exact pattern
+  // beats a subtree wildcard of the same length. Ties keep declaration order,
+  // which puts a file's `@security` header ahead of the def it annotates — the
+  // annotation is the app's own word on a middleware it may not own.
+  const scopeRank = (s: string[]) => s.length * 2 + (s[s.length - 1] === '*' ? 0 : 1)
+  const mwSecurity = [
+    ...mwMeta
+      .filter(m => hasSecurity(m.header.security))
+      .map(m => ({ segments: m.segments, security: m.header.security })),
+    ...g.middlewares.filter(m => hasSecurity(m.security)).map(m => ({ segments: m.segments, security: m.security! })),
+  ].sort((a, b) => scopeRank(b.segments) - scopeRank(a.segments))
+
+  // meta keys and spec paths are relative to basePath; route paths carry it
+  const prefix = g.router.prefix || ''
+  const relPath = (p: string) => (prefix && p.startsWith(prefix) ? p.slice(prefix.length) || '/' : p)
 
   walkRoutes(g.router.routes, r => {
-    let meta = metaRoutes?.[r.path]?.[r.method]
+    const rPath = relPath(r.path)
+    let meta = metaRoutes?.[rPath]?.[r.method]
+    const fileHeader = metaFileHeaders[rPath]
     if (r.static?.root) meta = metaStatic[r.static?.root]?.static
     if (meta?.hide) return
-    let path = r.path.replaceAll(/:([^\/]+)/g, '{$1}')
+    const rSegments = rPath.split('/').filter(s => s !== '')
+    const inherited = mwMeta.filter(m => matchMiddleware(m.segments, rSegments))
+    let path = rPath.replaceAll(/:([^\/]+)/g, '{$1}')
     if (!(path in paths)) paths[path] = {}
-    let tags = [
-      ...(meta?.tags?.split(' ')?.map((t: string) => t.trim()) || []),
-      ...(typeof meta?.tag === 'string' ? [meta?.tag] : meta?.tag || []),
+    const metaTags = (m?: Record<string, any>) => [
+      ...(m?.tags?.split?.(' ')?.map((t: string) => t.trim()) || []),
+      ...(typeof m?.tag === 'string' ? [m?.tag] : m?.tag || []),
     ]
-    let security: Record<string, any> = []
+    // tags accumulate from every scope that names one, nearest first
+    let tags = [...new Set([...metaTags(meta), ...metaTags(fileHeader), ...inherited.flatMap(m => metaTags(m.header))])]
+    let security: Record<string, any>[] = []
     let securityExplicitlyEmpty = false
 
-    const metaSecRaw = meta?.security
+    // nearest scope wins outright: the route, then its file's header, then the
+    // middleware covering it — file annotation or def, already ordered
+    const metaSecRaw =
+      meta?.security ?? fileHeader?.security ?? mwSecurity.find(m => matchMiddleware(m.segments, rSegments))?.security
     if (metaSecRaw !== undefined) {
       const entries = Array.isArray(metaSecRaw) ? metaSecRaw : [metaSecRaw]
       for (const e of entries) {
@@ -217,63 +364,74 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
       }
     }
 
+    // A scheme says which request field carries the credential, so the schema's
+    // own parameter for it is redundant: the operation documents it as auth, not
+    // as a plain header. Schemes are resolved wherever they were defined — the
+    // app config, a middleware def, or the bearerAuth default just above.
+    const credentialParams = new Set<string>()
+    for (const req of security) {
+      for (const name of Object.keys(req)) {
+        const scheme = components.securitySchemes?.[name]
+        if (!scheme || '$ref' in scheme) continue
+        if (scheme.type === 'http') credentialParams.add('header:authorization')
+        else if (scheme.type === 'apiKey' && scheme.name)
+          credentialParams.add(`${scheme.in}:${scheme.name.toLowerCase()}`)
+      }
+    }
+
     let pathParam = r.schema?.params
       ? Object.entries(r.schema?.params as Record<string, STSchema>).map(([k, v]) => parseParam(k, v, 'path'))
       : []
     let queryParam = r.schema?.query
       ? Object.entries(r.schema?.query as Record<string, STSchema>).map(([k, v]) => parseParam(k, v, 'query'))
       : []
-    const metaSecuritySet = security.length > 0
     let headerParam = r.schema?.headers
-      ? Object.entries(r.schema?.headers as Record<string, STSchema>)
-          .map(([k, v]) => {
-            let p = parseParam(k, v, 'header')
-            if (k.match(/authorization/i)) {
-              // TODO: handle other auth methods
-              const str = v as STString
-              if (str.pattern && str.pattern.toString() === '/^Bearer /') {
-                if (!metaSecuritySet) security.push({ bearerAuth: [] })
-                const scheme: OpenAPIV3.HttpSecurityScheme = { type: 'http', scheme: 'bearer' }
-                if (typeof str.format === 'string') scheme.bearerFormat = str.format
-                if (typeof str.description === 'string') scheme.description = str.description
-                if (!components.securitySchemes) components.securitySchemes = {}
-                components.securitySchemes.bearerAuth = scheme
-                return null
-              }
-            }
-            return p
-          })
-          .filter(p => p)
+      ? Object.entries(r.schema?.headers as Record<string, STSchema>).map(([k, v]) => parseParam(k, v, 'header'))
       : []
-    // TODO cookieParam
-    let parameters = [...pathParam, ...queryParam, ...headerParam]
+    let cookieParam = r.schema?.cookies
+      ? Object.entries(r.schema?.cookies as Record<string, STSchema>).map(([k, v]) => parseParam(k, v, 'cookie'))
+      : []
+    let parameters = [...pathParam, ...queryParam, ...headerParam, ...cookieParam]
+    if (credentialParams.size)
+      parameters = parameters.filter(p => p && !credentialParams.has(`${p.in}:${p.name.toLowerCase()}`))
 
     let requestBody
     if (r.schema.body) {
-      let description: string | undefined
-      let conflictDescription = false
+      // Like STResponseContent, a body map keys its bodies by media type; any
+      // other key (`description`, `required`, `_requestBodyId`) is metadata
+      // about the request body itself.
+      const bodyMap = r.schema.body as Record<string, any>
       let required = false
       let content = Object.fromEntries(
-        Object.entries(r.schema.body).map(([bodyType, schema]) => {
-          const s = schema.description
-          const isDefined = typeof s === 'string' && s !== ''
-          if (!schema?.[Optional]) required = true
-          if (isDefined) {
-            if (description === undefined) {
-              description = s
-            } else if (description !== s) {
-              conflictDescription = true
-            }
-          }
-          description = conflictDescription ? undefined : (description ?? undefined)
-          return [bodyType, { schema: schemaToOpenapi(schema).schema }]
-        })
+        Object.entries(bodyMap)
+          .filter(([bodyType, schema]) => bodyType.includes('/') && schema)
+          .map(([bodyType, schema]) => {
+            if (!schema?.[Optional]) required = true
+            // `encoding` belongs to the media type, not to the schema under it
+            const encoding = (schema as any)?.encoding
+            return [
+              bodyType,
+              {
+                schema: schemaToOpenapi(schema).schema,
+                ...(encoding && Object.keys(encoding).length ? { encoding } : {}),
+              },
+            ]
+          })
       )
+      // The body's own description comes from the body map and nowhere else.
+      // Deriving it from a body schema's `description` is wrong the moment the
+      // schema is a `$ref` to a documented component: that description belongs
+      // to the component, not to this operation's request body.
       requestBody = {
-        description,
-        required,
+        ...(typeof bodyMap.description === 'string' && bodyMap.description ? { description: bodyMap.description } : {}),
+        required: typeof bodyMap.required === 'boolean' ? bodyMap.required : required,
         content,
       }
+      // a body that came from components.requestBodies is emitted once and referenced
+      if (components.requestBodies && bodyMap._requestBodyId) {
+        components.requestBodies[bodyMap._requestBodyId as string] = requestBody
+        requestBody = { $ref: `#/components/requestBodies/${bodyMap._requestBodyId}` } as any
+      }
     }
     let responses
     if (r.schema.response && Object.keys(r.schema.response).length) {
@@ -281,32 +439,42 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
         Object.entries(r.schema.response).map(([status, v]) => {
           if (!v) return []
           let s = status as keyof typeof HttpStatus | 'default'
+          // `1XX`…`5XX` are status keys in their own right in OpenAPI; they
+          // carry no HttpStatus reason phrase, so they get a range description.
+          const statusDescription = HttpStatus[s as keyof typeof HttpStatus] ?? RESPONSE_RANGE_DESCRIPTION[status]
           const isContentMap = !(v as any)[Kind]
           const explicitHeaders = (v as any)?.responseHeaders as Record<string, STSchema> | undefined
           let response: OpenAPIV3.ResponseObject
 
           if (isContentMap) {
-            // STResponseContent — iterate body-type keys
+            // STResponseContent — every key holding a media type is a body; the
+            // rest (`description`, `example`, `examples`, `responseHeaders`,
+            // `_responseId`) is response-level metadata. Media types always
+            // contain a '/', which is what separates the two.
             const cm = v as any
-            const desc = cm.description || HttpStatus[s as keyof typeof HttpStatus] || 'Response'
+            const desc = cm.description || statusDescription || 'Response'
             const content: Record<string, { schema: any; example?: any; examples?: Record<string, any> }> = {}
             for (const [key, bodySchema] of Object.entries(cm)) {
-              if (key === 'description' || key === 'responseHeaders' || key === 'example' || key === 'examples') continue
+              if (!key.includes('/') || !bodySchema) continue
               const { schema: oaSchema } = schemaToOpenapi(bodySchema as STSchema)
               content[key] = { schema: oaSchema }
-              const ex = (bodySchema as any)?.examples
-              const exSingle = (bodySchema as any)?.example
+              // response-level example(s) apply to every media type offered
+              const ex = (bodySchema as any)?.examples ?? cm.examples
+              const exSingle = (bodySchema as any)?.example ?? cm.example
               if (ex && Object.keys(ex).length) content[key]!.examples = ex
               if (exSingle !== undefined) content[key]!.example = exSingle
             }
             response = { description: desc, ...(Object.keys(content).length ? { content } : {}) }
           } else {
-            const statusNum = Number(s)
-            const noBodyStatus = statusNum === 204 || statusNum === 304 || (statusNum >= 100 && statusNum < 200)
-            const noContent = noBodyStatus && (v as any)[Kind] === 'null'
+            // A bare `null`-kind response schema means "this response has no
+            // body", at every status — not just the ones where HTTP forbids
+            // one. A genuine JSON `null` body stays expressible, and reads
+            // unambiguously, through the content-map form
+            // `{'application/json': $T.null()}`.
+            const noContent = (v as any)[Kind] === 'null'
             if (noContent) {
               response = {
-                description: (v as any).description || HttpStatus[s as keyof typeof HttpStatus] || 'Response',
+                description: (v as any).description || statusDescription || 'Response',
               }
             } else {
               let { schema, isJson } = schemaToOpenapi(v as STSchema)
@@ -316,23 +484,18 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
               const mediaType = schemaToMedia({ type, format, isJson } as SchemaType, hasComposite)
               const explicitExamples = (v as any)?.examples as Record<string, any> | undefined
               const explicitExample = (v as any)?.example
-              const content: Record<string, { schema: typeof schema; example?: any; examples?: Record<string, any> }> = {
-                [mediaType]: { schema: { ...schema } },
-              }
-              if (explicitExamples && Object.keys(explicitExamples).length) content[mediaType]!.examples = explicitExamples
+              const content: Record<string, { schema: typeof schema; example?: any; examples?: Record<string, any> }> =
+                {
+                  [mediaType]: { schema: { ...schema } },
+                }
+              if (explicitExamples && Object.keys(explicitExamples).length)
+                content[mediaType]!.examples = explicitExamples
               if (explicitExample !== undefined) content[mediaType]!.example = explicitExample
               response = {
-                description: (v as any).description || HttpStatus[s as keyof typeof HttpStatus] || 'Response',
+                description: (v as any).description || statusDescription || 'Response',
                 content,
               }
             }
-            const respSchema = r.schema.response?.[s] as any
-            const respId = respSchema?._responseId
-            if (components.responses && respId) {
-              components.responses[respId as string] = response
-              //@ts-ignore
-              response = { $ref: `#/components/responses/${respId}` }
-            }
           }
 
           if (explicitHeaders && Object.keys(explicitHeaders).length) {
@@ -350,6 +513,21 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
               response.headers[hName] = headerObj
             }
           }
+
+          // `links` is carried verbatim: Galbe models no operation graph, so
+          // there is nothing to derive it from and nothing to validate it against.
+          const explicitLinks = (v as any)?.responseLinks as Record<string, any> | undefined
+          if (explicitLinks && Object.keys(explicitLinks).length) response.links = explicitLinks
+
+          // `_responseId` marks a response that came from components.responses.
+          // Register the fully-built response — headers included — and refer to
+          // it: a Reference Object tolerates no sibling keys in 3.0.
+          const respId = (v as any)?._responseId
+          if (components.responses && respId) {
+            components.responses[respId as string] = response
+            //@ts-ignore
+            response = { $ref: `#/components/responses/${respId}` }
+          }
           return [s, response]
         })
       )
@@ -358,23 +536,21 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
         default: { description: HttpStatus[200] },
       }
     }
-    const head: string = meta?.head ?? ''
-    let summary: string | undefined
-    let description: string | undefined
-    if (head) {
-      const firstBlank = head.indexOf('\n\n')
-      if (firstBlank === -1) {
-        const nl = head.indexOf('\n')
-        summary = (nl === -1 ? head : head.slice(0, nl)).trim() || undefined
-      } else {
-        summary = head.slice(0, firstBlank).trim() || undefined
-        description = head.slice(firstBlank + 2).trim() || undefined
-      }
+    const { summary, description } = routeHead(meta)
+    // `@externalDocs <url> [description]` — the url runs to the first
+    // whitespace, everything after it is the docs' description.
+    const extDocsRaw = Array.isArray(meta?.externalDocs) ? meta.externalDocs[0] : meta?.externalDocs
+    let externalDocs: OpenAPIV3.ExternalDocumentationObject | undefined
+    if (typeof extDocsRaw === 'string' && extDocsRaw.trim()) {
+      const [url, ...rest] = extDocsRaw.trim().split(/\s+/)
+      const docsDescription = rest.join(' ')
+      externalDocs = { url: url!, ...(docsDescription ? { description: docsDescription } : {}) }
     }
     paths[path][r.method] = {
       tags: tags.length ? tags : undefined,
       summary,
       description,
+      externalDocs,
       operationId: meta?.operationId,
       parameters: parameters.length ? parameters : undefined,
       requestBody,
@@ -448,7 +624,19 @@ export const OpenAPISerializer = async (g: Galbe, version = '3.0.3'): Promise<Op
     info: {
       title: 'Galbe app',
       version: '0.1.0',
+      ...g.config?.openapi?.info,
     },
+    // basePath is a deploy location, not API structure: it is stripped from
+    // `paths` and surfaced through `servers` unless explicitly configured
+    ...(g.config?.openapi?.servers
+      ? { servers: g.config.openapi.servers }
+      : prefix
+        ? { servers: [{ url: prefix }] }
+        : {}),
+    // document-level blocks belong to no route: they are declared in GalbeConfig
+    ...(g.config?.openapi?.tags ? { tags: g.config.openapi.tags } : {}),
+    ...(g.config?.openapi?.security ? { security: g.config.openapi.security } : {}),
+    ...(g.config?.openapi?.externalDocs ? { externalDocs: g.config.openapi.externalDocs } : {}),
     paths,
     components: Object.keys(components)?.length ? components : undefined,
   }

package/src/extras.ts

@@ -1,2 +1,2 @@
 export { OpenAPISerializer } from './extras/spec/openapi.serializer'
-export type { GalbeCLICommand, GalbeCLIOptions, GalbeClientRoute, GalbeClientOptions } from './types'
+export type { GalbeCLICommand, GalbeCLIOptions, GalbeClientRoute, GalbeClientOptions, OpenAPIConfig } from './types'