@specbook/codegen 0.9.1 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/codegen",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Turns an OpenAPI or Swagger document into types, examples, schemas and metadata, in Node or in a browser.",
   "keywords": [
     "specbook",
@@ -44,7 +44,7 @@
     "swagger2openapi": "7.0.8"
   },
   "devDependencies": {
-    "@specbook/core": "0.9.1",
+    "@specbook/core": "0.11.0",
     "@types/node": "24.19.2",
     "@types/swagger2openapi": "7.0.4",
     "typescript": "7.0.2"

package/src/browser.ts

@@ -13,7 +13,9 @@ export type {
   GenerateFlags,
   GenerateOptions,
   ManifestOperation,
+  ManifestSecurityScheme,
   OperationMeta,
+  ResponseDoc,
 } from './build'
 export { generateFromDoc, logoOf } from './build'
 

package/src/build.ts

@@ -73,6 +73,13 @@ interface ExampleDoc {
   body?: unknown
 }
 
+/** What `docs/<id>.json` says about one response, for the Docs tab. */
+export interface ResponseDoc {
+  description?: string
+  /** the media type the body is written in, as the spec names it */
+  contentType?: string
+}
+
 export interface ManifestOperation {
   id: string
   method: string
@@ -89,9 +96,55 @@ export interface ManifestOperation {
   examples: ManifestExample[]
   /** the spec requires credentials for this operation */
   secured?: boolean
+  /** any one of these is enough; every scheme in one entry must apply together, with the scopes it needs */
+  security?: Record<string, string[]>[]
   file: string
 }
 
+/** What a security scheme is, without addresses or descriptions: enough to say how an operation is secured. */
+export interface ManifestSecurityScheme {
+  type: string
+  in?: string
+  name?: string
+  scheme?: string
+  openIdConnectUrl?: string
+  /** flow name -> its scope names */
+  flows?: Record<string, { scopes: string[] }>
+}
+
+/** The document's security schemes in the manifest's compact form. */
+export function securitySchemesOf(doc: any): Record<string, ManifestSecurityScheme> {
+  const out: Record<string, ManifestSecurityScheme> = {}
+  for (const [name, s] of Object.entries<any>(doc.components?.securitySchemes ?? {})) {
+    if (!s || typeof s.type !== 'string') continue
+    const flows = Object.fromEntries(
+      Object.entries<any>(s.flows ?? {}).map(([f, v]) => [
+        f,
+        { scopes: Object.keys(v?.scopes ?? {}) },
+      ]),
+    )
+    out[name] = {
+      type: s.type,
+      ...(typeof s.in === 'string' ? { in: s.in } : {}),
+      ...(typeof s.name === 'string' ? { name: s.name } : {}),
+      ...(typeof s.scheme === 'string' ? { scheme: s.scheme } : {}),
+      ...(typeof s.openIdConnectUrl === 'string' ? { openIdConnectUrl: s.openIdConnectUrl } : {}),
+      ...(Object.keys(flows).length ? { flows } : {}),
+    }
+  }
+  return out
+}
+
+/** An operation's requirements as a plain list of `{ scheme: scopes }`. */
+function requirementsFrom(effective: unknown): Record<string, string[]>[] {
+  if (!Array.isArray(effective)) return []
+  return effective.map((r: any) =>
+    Object.fromEntries(
+      Object.entries(r ?? {}).map(([k, v]) => [k, Array.isArray(v) ? v.map(String) : []]),
+    ),
+  )
+}
+
 /** `info.x-logo` (a Redoc convention): only absolute http(s) or data-image URLs are trusted. */
 export function logoOf(
   info: any,
@@ -128,6 +181,7 @@ function findJsonLike(content: Record<string, any> | undefined) {
         schema: content[mime].schema as Schema | undefined,
         encoding: enc,
         media: content[mime],
+        mime,
       }
   }
   const json = Object.keys(content).find((m) => /json/.test(m))
@@ -136,6 +190,7 @@ function findJsonLike(content: Record<string, any> | undefined) {
       schema: content[json].schema as Schema | undefined,
       encoding: 'json',
       media: content[json],
+      mime: json,
     }
   const binary = Object.keys(content).find((m) => BINARY_MIME.test(m))
   if (binary)
@@ -143,6 +198,7 @@ function findJsonLike(content: Record<string, any> | undefined) {
       schema: content[binary].schema as Schema | undefined,
       encoding: 'binary',
       media: content[binary],
+      mime: binary,
       mediaType: binary,
     }
   // A wildcard stands for whatever the server sends, and a framework that is not told what it produces
@@ -155,6 +211,7 @@ function findJsonLike(content: Record<string, any> | undefined) {
       schema,
       encoding: file ? 'binary' : 'json',
       media: content[any],
+      mime: any,
       ...(file ? { mediaType: any } : {}),
     }
   }
@@ -245,7 +302,8 @@ export interface OperationMeta {
   mediaType?: string
   files?: string[]
   formArrays?: Record<string, string>
-  security?: boolean
+  /** `false` = none required; otherwise any one of the requirements (see `ManifestOperation.security`) */
+  security?: false | Record<string, string[]>[]
 }
 
 /** The generator proper, from an OpenAPI 3 document that is already parsed and bundled. */
@@ -497,6 +555,18 @@ function generateAll(
       let defaultSchema: Schema | undefined
       const responseSchemas: Record<string, Schema> = {}
       const mockVariants: NonNullable<ManifestOperation['mockVariants']> = {}
+      const responseDocs: Record<string, ResponseDoc> = {}
+      let defaultDoc: ResponseDoc | undefined
+      const docOf = (res: any, found: { mime?: string } | undefined): ResponseDoc | undefined => {
+        const description =
+          typeof res?.description === 'string' && res.description.trim()
+            ? res.description.trim()
+            : undefined
+        const contentType = found?.mime ?? Object.keys(res?.content ?? {})[0]
+        return description || contentType
+          ? { ...(description ? { description } : {}), ...(contentType ? { contentType } : {}) }
+          : undefined
+      }
       let defaultVariants: ManifestOperation['mockVariants'] extends infer M
         ? M extends Record<string, infer V>
           ? V | undefined
@@ -504,7 +574,9 @@ function generateAll(
         : never
       for (const [code, rawRes] of Object.entries<any>(op.responses ?? {})) {
         if (code === 'default') {
-          const found = findJsonLike(resolveAny<any>(rawRes)?.content)
+          const defaultRes = resolveAny<any>(rawRes)
+          const found = findJsonLike(defaultRes?.content)
+          defaultDoc = docOf(defaultRes, found)
           if (found?.schema) {
             hasDefault = true
             if (ts) defaultType = tsType(found.schema, '  ', 'T.')
@@ -522,6 +594,8 @@ function generateAll(
         const res = resolveAny<any>(rawRes)
         const found = findJsonLike(res?.content)
         statuses.push(Number(code))
+        const responseDoc = docOf(res, found)
+        if (responseDoc) responseDocs[code] = responseDoc
         if (found?.schema) responseSchemas[code] = toJsonSchema(found.schema, `${defsId}#/$defs/`)
         if (ts)
           responseTypes.push(
@@ -540,6 +614,7 @@ function generateAll(
         for (const st of DEFAULT_ERROR_STATUSES) {
           if (statuses.includes(st)) continue
           statuses.push(st)
+          if (defaultDoc) responseDocs[String(st)] = defaultDoc
           if (defaultSchema) responseSchemas[String(st)] = defaultSchema
           if (defaultVariants) mockVariants[String(st)] = defaultVariants
           if (defaultType) responseTypes.push(`${st}: ${defaultType}`)
@@ -643,9 +718,10 @@ function generateAll(
 
       const effective = op.security ?? doc.security
       const secured = hasSchemes && Array.isArray(effective) && effective.length > 0
+      const requirements = requirementsFrom(effective)
       const securityLine = !hasSchemes
         ? ''
-        : `, security: ${Array.isArray(effective) && effective.length > 0 ? 'true' : 'false'}`
+        : `, security: ${requirements.length > 0 ? JSON.stringify(requirements) : 'false'}`
       // a binary body's declared type (`application/octet-stream`) is what the server expects as Content-Type
       const mediaType =
         body &&
@@ -673,7 +749,9 @@ function generateAll(
         ...(mediaType ? { mediaType } : {}),
         ...(fileFieldPaths.length ? { files: fileFieldPaths } : {}),
         ...(Object.keys(arrayStyles).length ? { formArrays: arrayStyles } : {}),
-        ...(hasSchemes ? { security: Array.isArray(effective) && effective.length > 0 } : {}),
+        ...(hasSchemes
+          ? { security: requirements.length > 0 ? requirements : (false as const) }
+          : {}),
       }
       if (ts)
         files.push({
@@ -696,6 +774,7 @@ ${jsdoc({ description: [...new Set([op.summary, op.description].filter(Boolean))
         content: `${JSON.stringify({
           ...(op.description && op.description !== summary ? { description: op.description } : {}),
           examples: docs.map((d) => ({ name: d.name, title: d.title, source: d.source })),
+          ...(Object.keys(responseDocs).length ? { responses: responseDocs } : {}),
         })}\n`,
       })
       operations.push({
@@ -708,7 +787,7 @@ ${jsdoc({ description: [...new Set([op.summary, op.description].filter(Boolean))
         statuses,
         ...(Object.keys(mockVariants).length ? { mockVariants } : {}),
         examples: docs.map((d) => ({ name: d.name, title: d.title, source: d.source })),
-        ...(secured ? { secured: true } : {}),
+        ...(secured ? { secured: true, security: requirements } : {}),
         file: `operations/${id}.ts`,
       })
     }
@@ -742,6 +821,7 @@ ${jsdoc({ description: [...new Set([op.summary, op.description].filter(Boolean))
         version: doc.info?.version,
         ...(logoOf(doc.info) ? { logo: logoOf(doc.info) } : {}),
         servers: (doc.servers ?? []).map((s: any) => s.url),
+        ...(hasSchemes ? { securitySchemes: securitySchemesOf(doc) } : {}),
         tags: [...byTag.keys()],
         operations,
       },

package/src/index.ts

@@ -3,6 +3,7 @@ export type {
   GenerateFlags,
   GenerateOptions,
   ManifestOperation,
+  ManifestSecurityScheme,
   OperationMeta,
 } from './build'
 export { generate, generateFromDoc, withPlainSpec } from './generate'