blume 1.4.3 → 1.5.1

package/src/components/openapi/async.ts

@@ -0,0 +1,348 @@
+import type {
+  AsyncApiChannelObject,
+  AsyncApiDocument,
+  AsyncApiOperationObject,
+  AsyncApiRefLike,
+  AsyncApiServerObject,
+  AsyncApiSpecValue,
+} from "../../openapi/asyncapi.ts";
+import type { ParameterLike, SchemaLike } from "./helpers.ts";
+import { resolveComponentRef } from "./helpers.ts";
+
+/**
+ * Runtime helpers for the AsyncAPI components — the async counterpart of
+ * `helpers.ts`. These operate on the normalized 3.x document behind the
+ * `blume:openapi` alias, resolving the ref shapes AsyncAPI adds on top of
+ * `#/components/*`: operations point at channels, channel messages may `$ref`
+ * `#/components/messages`, and operation messages point *into* a channel
+ * (`#/channels/<id>/messages/<name>`). Browser-safe like the rest of the set.
+ */
+
+/** A permissive view of an AsyncAPI message — only the fields we render. */
+export interface AsyncApiMessageLike extends AsyncApiRefLike {
+  name?: string;
+  title?: string;
+  summary?: string;
+  description?: string;
+  contentType?: string;
+  payload?: AsyncApiSpecValue;
+  headers?: AsyncApiSpecValue;
+  examples?: {
+    name?: string;
+    summary?: string;
+    payload?: AsyncApiSpecValue;
+    headers?: AsyncApiSpecValue;
+  }[];
+  bindings?: AsyncApiChannelObject["bindings"];
+}
+
+/** A message paired with its channel-map key (the fallback display name). */
+export interface NamedMessage {
+  key: string;
+  message: AsyncApiMessageLike;
+}
+
+const isObject = (
+  value: AsyncApiSpecValue
+): value is Record<string, AsyncApiSpecValue> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Permissive spec nodes may lie about declared string fields; verify first. */
+const isString = (value: AsyncApiSpecValue): value is string =>
+  typeof value === "string";
+
+/** Decode a JSON-pointer token: `user~1signedup` -> `user/signedup`. */
+const unescapePointer = (token: string): string =>
+  token.replaceAll("~1", "/").replaceAll("~0", "~");
+
+const CHANNEL_MESSAGE_REF =
+  /^#\/channels\/(?<channel>.+)\/messages\/(?<name>[^/]+)$/u;
+
+type Components = AsyncApiDocument["components"];
+
+/** Resolve a channel-map message (possibly a components `$ref`) to its object. */
+const channelMessage = (
+  raw: AsyncApiRefLike | undefined,
+  components: Components
+): AsyncApiMessageLike | undefined => {
+  if (!isObject(raw)) {
+    return undefined;
+  }
+  const resolved = resolveComponentRef(raw, components, "messages");
+  // Still a bare `$ref` after resolution means it pointed nowhere useful.
+  if (isString(resolved.$ref)) {
+    return undefined;
+  }
+  // SAFETY: `resolved` is a plain message object; the permissive message view
+  // only narrows the fields the components render, all of them optional.
+  return resolved as AsyncApiMessageLike;
+};
+
+/**
+ * The messages one operation carries: its own `messages` refs when declared
+ * (each pointing into the channel's message map or at a components message),
+ * else every message the channel declares. Unresolvable refs are dropped —
+ * the schema tables can only render an actual message object.
+ */
+export const operationMessages = (
+  operation: AsyncApiOperationObject | undefined,
+  channel: AsyncApiChannelObject | undefined,
+  document: AsyncApiDocument
+): NamedMessage[] => {
+  const { components } = document;
+  const messageMap: Record<string, AsyncApiRefLike> = isObject(
+    channel?.messages
+  )
+    ? channel.messages
+    : {};
+  const refs = operation?.messages;
+  if (!Array.isArray(refs) || refs.length === 0) {
+    const all: NamedMessage[] = [];
+    for (const [key, raw] of Object.entries(messageMap)) {
+      const message = channelMessage(raw, components);
+      if (message) {
+        all.push({ key, message });
+      }
+    }
+    return all;
+  }
+  const named: NamedMessage[] = [];
+  for (const ref of refs) {
+    if (!isObject(ref)) {
+      continue;
+    }
+    const pointer = isString(ref.$ref)
+      ? CHANNEL_MESSAGE_REF.exec(ref.$ref)?.groups?.name
+      : undefined;
+    const key = pointer === undefined ? undefined : unescapePointer(pointer);
+    // A channel-message pointer resolves through the channel map; anything
+    // else (a components ref, an inline message) resolves directly.
+    const message =
+      key === undefined
+        ? channelMessage(ref, components)
+        : channelMessage(messageMap[key], components);
+    if (message) {
+      named.push({ key: key ?? message.name ?? "message", message });
+    }
+  }
+  return named;
+};
+
+/** A message's display name: its `name`/`title`, else its channel-map key. */
+export const messageLabel = (named: NamedMessage): string =>
+  named.message.title ?? named.message.name ?? named.key;
+
+/**
+ * The `schemaFormat` media types whose schemas render as JSON Schema: the
+ * AsyncAPI Schema Object (a JSON Schema superset), OpenAPI Schema Objects,
+ * and JSON Schema itself, in their bare and `+json`/`+yaml` spellings.
+ */
+const JSON_SCHEMA_FORMAT =
+  /^application\/(?:vnd\.aai\.asyncapi|vnd\.oai\.openapi|schema)(?:\+(?:json|yaml))?$/u;
+
+/**
+ * The JSON-schema view of a possibly multi-format schema value
+ * (`{ schemaFormat, schema }`, allowed on both message payloads and headers).
+ * Unwraps when the format is JSON-schema compatible and yields nothing
+ * otherwise (an Avro or Protobuf schema can't render as a schema table —
+ * callers fall back to a note).
+ */
+export const schemaOf = (value: AsyncApiSpecValue): SchemaLike | undefined => {
+  if (!isObject(value)) {
+    return undefined;
+  }
+  if (isString(value.schemaFormat) && "schema" in value) {
+    // Match the media type proper (parameters like `;version=…` stripped)
+    // against the JSON-Schema-compatible formats AsyncAPI registers. A
+    // substring test would misclassify e.g. Avro's `+json` encoding, whose
+    // schema is JSON but not JSON Schema.
+    const format = (value.schemaFormat.split(";")[0] ?? "")
+      .trim()
+      .toLowerCase();
+    const jsonish = JSON_SCHEMA_FORMAT.test(format);
+    if (jsonish && isObject(value.schema)) {
+      // SAFETY: a JSON-Schema-format schema object; the permissive SchemaLike
+      // view only narrows the fields the schema tables render, all optional.
+      return value.schema as SchemaLike;
+    }
+    return undefined;
+  }
+  // SAFETY: a bare schema object; the permissive SchemaLike view only narrows
+  // the fields the schema tables render, all of them optional.
+  return value as SchemaLike;
+};
+
+/** The JSON-schema view of a message payload; see {@link schemaOf}. */
+export const payloadSchema = (
+  message: AsyncApiMessageLike
+): SchemaLike | undefined => schemaOf(message.payload);
+
+/** The channel-parameter fields {@link channelParameters} lowers. */
+interface AsyncApiParameterLike extends AsyncApiRefLike {
+  description?: string;
+  default?: AsyncApiSpecValue;
+  enum?: AsyncApiSpecValue[];
+}
+
+/**
+ * Channel parameters lowered into the shared parameter-table shape. AsyncAPI
+ * 3.x parameters are always strings (`enum`/`default`/`examples`, no schema),
+ * and every one is required — an address template can't resolve without it.
+ */
+export const channelParameters = (
+  channel: AsyncApiChannelObject | undefined,
+  document: AsyncApiDocument
+): ParameterLike[] => {
+  const parameters: ParameterLike[] = [];
+  const declared: Record<string, AsyncApiRefLike> = channel?.parameters ?? {};
+  for (const [name, raw] of Object.entries(declared)) {
+    if (!isObject(raw)) {
+      continue;
+    }
+    // SAFETY: the permissive parameter view only narrows the fields lowered
+    // below; each one is runtime-checked before use.
+    const parameter = resolveComponentRef(
+      raw as AsyncApiParameterLike,
+      document.components,
+      "parameters"
+    );
+    const schema: SchemaLike = { type: "string" };
+    if (Array.isArray(parameter.enum)) {
+      schema.enum = parameter.enum;
+    }
+    if (parameter.default !== undefined) {
+      schema.default = parameter.default;
+    }
+    parameters.push({
+      description: isString(parameter.description)
+        ? parameter.description
+        : undefined,
+      in: "channel",
+      name,
+      required: true,
+      schema,
+    });
+  }
+  return parameters;
+};
+
+const SERVER_REF = /^#\/servers\/(?<name>[^/]+)$/u;
+
+/**
+ * The servers a channel is available on: its `servers` refs when declared,
+ * else every server the document declares (the spec's default).
+ */
+export const channelServers = (
+  channel: AsyncApiChannelObject | undefined,
+  document: AsyncApiDocument
+): AsyncApiServerObject[] => {
+  const all = document.servers ?? {};
+  const refs = channel?.servers;
+  if (!Array.isArray(refs) || refs.length === 0) {
+    return Object.values(all).filter(isObject);
+  }
+  const servers: AsyncApiServerObject[] = [];
+  for (const ref of refs) {
+    const name = SERVER_REF.exec(
+      isObject(ref) && isString(ref.$ref) ? ref.$ref : ""
+    )?.groups?.name;
+    const server = name === undefined ? undefined : all[unescapePointer(name)];
+    if (isObject(server)) {
+      servers.push(server);
+    }
+  }
+  return servers;
+};
+
+/** Normalize protocol spellings onto the binding key they document. */
+const PROTOCOL_ALIASES = {
+  "kafka-secure": "kafka",
+  mqtt5: "mqtt",
+  mqtts: "mqtt",
+  "secure-mqtt": "mqtt",
+  wss: "ws",
+};
+
+/**
+ * The protocol an operation speaks, for binding-aware code samples: the first
+ * operation/channel binding key, else the first relevant server's `protocol`.
+ */
+export const protocolOf = (
+  operation: AsyncApiOperationObject | undefined,
+  channel: AsyncApiChannelObject | undefined,
+  servers: AsyncApiServerObject[]
+): string | undefined => {
+  const declared =
+    Object.keys(operation?.bindings ?? {})[0] ??
+    Object.keys(channel?.bindings ?? {})[0] ??
+    servers.find((server) => isString(server.protocol))?.protocol;
+  if (!isString(declared) || declared === "") {
+    return undefined;
+  }
+  const lower = declared.toLowerCase();
+  // SAFETY: guarded by the `in` check, `lower` is one of the alias keys.
+  return lower in PROTOCOL_ALIASES
+    ? PROTOCOL_ALIASES[lower as keyof typeof PROTOCOL_ALIASES]
+    : lower;
+};
+
+/**
+ * The security list an operation actually enforces: its own `security` when
+ * declared, else the union of its servers' — connecting already requires the
+ * server's schemes. Server entries dedupe by `$ref`, so two servers sharing a
+ * scheme render it once.
+ */
+export const asyncApiSecurityEntries = (
+  operation: AsyncApiOperationObject | undefined,
+  servers: AsyncApiServerObject[]
+): AsyncApiRefLike[] => {
+  if (Array.isArray(operation?.security)) {
+    return operation.security;
+  }
+  const entries: AsyncApiRefLike[] = [];
+  const seen = new Set<string>();
+  for (const server of servers) {
+    for (const entry of server.security ?? []) {
+      if (!isObject(entry)) {
+        continue;
+      }
+      if (isString(entry.$ref)) {
+        if (seen.has(entry.$ref)) {
+          continue;
+        }
+        seen.add(entry.$ref);
+      }
+      entries.push(entry);
+    }
+  }
+  return entries;
+};
+
+/** One protocol's binding fields, ready for a key/value table. */
+export interface BindingGroup {
+  protocol: string;
+  rows: { name: string; value: unknown }[];
+}
+
+/**
+ * Binding maps flattened for display, `bindingVersion` (metadata, not
+ * behavior) dropped. Values stay unformatted — the component renders schema-ish
+ * objects as nested schema tables and everything else as code.
+ */
+export const bindingGroups = (
+  bindings?: AsyncApiChannelObject["bindings"]
+): BindingGroup[] => {
+  const groups: BindingGroup[] = [];
+  for (const [protocol, fields] of Object.entries(bindings ?? {})) {
+    if (!isObject(fields)) {
+      continue;
+    }
+    const rows = Object.entries(fields)
+      .filter(([name]) => name !== "bindingVersion")
+      .map(([name, value]) => ({ name, value }));
+    if (rows.length > 0) {
+      groups.push({ protocol, rows });
+    }
+  }
+  return groups;
+};

package/src/components/openapi/helpers.ts

@@ -8,6 +8,22 @@ import { sample } from "openapi-sampler";
  * values come from openapi-sampler, which is likewise browser-safe.
  */
 
+/** Any value a parsed OpenAPI document can hold: JSON, nested schemas included. */
+export type SpecValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | SpecValue[]
+  | { [key: string]: SpecValue };
+
+const isString = (value: SpecValue): value is string =>
+  typeof value === "string";
+
+const isNumber = (value: SpecValue): value is number =>
+  typeof value === "number";
+
 /** A permissive view of an OpenAPI 3.1 schema — only the fields we render. */
 export interface SchemaLike {
   $ref?: string;
@@ -18,11 +34,11 @@ export interface SchemaLike {
   properties?: Record<string, SchemaLike>;
   required?: string[];
   items?: SchemaLike;
-  enum?: unknown[];
-  const?: unknown;
-  default?: unknown;
-  example?: unknown;
-  examples?: unknown[];
+  enum?: SpecValue[];
+  const?: SpecValue;
+  default?: SpecValue;
+  example?: SpecValue;
+  examples?: SpecValue[];
   allOf?: SchemaLike[];
   oneOf?: SchemaLike[];
   anyOf?: SchemaLike[];
@@ -38,7 +54,7 @@ export interface SchemaLike {
   minItems?: number;
   maxItems?: number;
   pattern?: string;
-  [key: string]: unknown;
+  [key: string]: SpecValue;
 }
 
 /** A permissive view of an operation parameter — only the fields we render. */
@@ -50,9 +66,16 @@ export interface ParameterLike {
   required?: boolean;
   deprecated?: boolean;
   schema?: SchemaLike;
-  example?: unknown;
+  example?: SpecValue;
+  [key: string]: SpecValue;
 }
 
+/** The `components` object of a parsed spec: section name → named-node table. */
+export type ComponentsLike = Record<
+  string,
+  Record<string, SpecValue> | undefined
+>;
+
 const REF_PATTERN = /#\/components\/schemas\/(?<name>[^/]+)$/u;
 
 const COMPONENT_REF = /#\/components\/(?<section>[^/]+)\/(?<name>[^/]+)$/u;
@@ -65,16 +88,18 @@ const COMPONENT_REF = /#\/components\/(?<section>[^/]+)\/(?<name>[^/]+)$/u;
  */
 export const resolveComponentRef = <T extends { $ref?: string }>(
   node: T,
-  components: Record<string, unknown> | undefined,
+  components: ComponentsLike | undefined,
   section: string
 ): T => {
-  if (typeof node.$ref !== "string") {
+  if (!isString(node.$ref)) {
     return node;
   }
   const groups = COMPONENT_REF.exec(node.$ref)?.groups;
   if (groups?.section !== section) {
     return node;
   }
+  // SAFETY: a components section table stores nodes of that section's type,
+  // and callers always pair `section` with the matching `T`.
   const table = components?.[section] as Record<string, T> | undefined;
   return table?.[groups.name ?? ""] ?? node;
 };
@@ -88,7 +113,7 @@ export const resolveComponentRef = <T extends { $ref?: string }>(
 export const mergeParameters = (
   pathParameters: ParameterLike[] | undefined,
   operationParameters: ParameterLike[] | undefined,
-  components?: Record<string, unknown>
+  components?: ComponentsLike
 ): ParameterLike[] => {
   const merged = new Map<string, ParameterLike>();
   let position = 0;
@@ -118,7 +143,7 @@ export const resolveSchema = (
   if (!schema) {
     return {};
   }
-  if (typeof schema.$ref === "string") {
+  if (isString(schema.$ref)) {
     const name = REF_PATTERN.exec(schema.$ref)?.groups?.name;
     if (name && schemas[name]) {
       return schemas[name];
@@ -140,7 +165,7 @@ const nonNullTypes = (type: string | string[] | undefined): string[] => {
  * array items can't recurse forever.
  */
 export const typeLabel = (schema: SchemaLike): string => {
-  if (typeof schema.$ref === "string") {
+  if (isString(schema.$ref)) {
     return refName(schema.$ref);
   }
   if (schema.oneOf || schema.anyOf) {
@@ -177,11 +202,11 @@ export const constraints = (schema: SchemaLike): string[] => {
   ];
   for (const [key, label] of numeric) {
     const value = schema[key];
-    if (typeof value === "number") {
+    if (isNumber(value)) {
       out.push(`${label} ${value}`);
     }
   }
-  if (typeof schema.pattern === "string") {
+  if (isString(schema.pattern)) {
     out.push(`matches ${schema.pattern}`);
   }
   if (schema.default !== undefined) {
@@ -190,6 +215,12 @@ export const constraints = (schema: SchemaLike): string[] => {
   return out;
 };
 
+/** The merged property list and required set a schema exposes. */
+export interface ObjectPropertySet {
+  properties: [string, SchemaLike][];
+  required: Set<string>;
+}
+
 /**
  * The object properties a schema exposes, merging `allOf` branches so an
  * `allOf`-composed model still lists every field. Returns the properties plus
@@ -198,7 +229,7 @@ export const constraints = (schema: SchemaLike): string[] => {
 export const objectProperties = (
   schema: SchemaLike,
   schemas: Record<string, SchemaLike>
-): { properties: [string, SchemaLike][]; required: Set<string> } => {
+): ObjectPropertySet => {
   const properties = new Map<string, SchemaLike>();
   const required = new Set<string>();
   // Cycles can only enter through `$ref`s (inline JSON can't self-nest), so
@@ -206,7 +237,7 @@ export const objectProperties = (
   const seen = new Set<string>();
 
   const collect = (node: SchemaLike): void => {
-    if (typeof node.$ref === "string") {
+    if (isString(node.$ref)) {
       if (seen.has(node.$ref)) {
         return;
       }
@@ -239,16 +270,18 @@ export const objectProperties = (
 export const exampleValue = (
   schema: SchemaLike | undefined,
   schemas: Record<string, SchemaLike>
-): unknown => {
+): SpecValue => {
   if (!schema) {
     return null;
   }
   try {
+    // SAFETY: SchemaLike structurally covers the JSONSchema7 fields the
+    // sampler reads, and the sampler only ever assembles JSON values.
     return sample(
       schema as Parameters<typeof sample>[0],
       { quiet: true, skipReadOnly: true },
       { components: { schemas } }
-    );
+    ) as SpecValue;
   } catch {
     // An unresolvable $ref or malformed schema is a spec problem the schema
     // tables already surface; a sample is best-effort.
@@ -257,5 +290,4 @@ export const exampleValue = (
 };
 
 /** Pretty-print a JSON value for an example/code block. */
-export const toJson = (value: unknown): string =>
-  JSON.stringify(value, null, 2);
+export const toJson = <T>(value: T): string => JSON.stringify(value, null, 2);

package/src/components/openapi/security.ts

@@ -20,7 +20,6 @@ export interface SecuritySchemeLike {
   scheme?: string;
   /** `http` bearer: a hint at the token format, e.g. `JWT`. */
   bearerFormat?: string;
-  [key: string]: unknown;
 }
 
 /** One security requirement: scheme name -> required scopes (empty outside OAuth). */
@@ -85,42 +84,115 @@ export const resolveSecurity = (
   return { alternatives, optional };
 };
 
+/**
+ * One AsyncAPI 3.x security entry: a `$ref` into
+ * `components.securitySchemes`, or an inline scheme object (the shape the
+ * official 2.x converter emits for scoped requirements, `scopes` on the
+ * scheme itself).
+ */
+export interface AsyncApiSecurityEntryLike {
+  $ref?: string;
+  type?: string;
+  scopes?: unknown;
+}
+
+const SECURITY_SCHEME_REF = /^#\/components\/securitySchemes\/(?<name>[^/]+)$/u;
+
+/** Runtime string check for spec fields a hand-written document may corrupt. */
+const isSpecString = (value: string | undefined): value is string =>
+  typeof value === "string";
+
+/** Parsed YAML can put anything in a security list; keep only real objects. */
+const isSecurityEntryObject = (
+  entry: AsyncApiSecurityEntryLike
+): entry is AsyncApiSecurityEntryLike =>
+  typeof entry === "object" && entry !== null;
+
+/** Decode a JSON-pointer token: `kafka~1sasl` -> `kafka/sasl`. */
+const unescapePointer = (token: string): string =>
+  token.replaceAll("~1", "/").replaceAll("~0", "~");
+
+/**
+ * Resolve an AsyncAPI 3.x security list. Unlike OpenAPI's requirement maps,
+ * each entry names a single scheme and any one entry satisfies the operation
+ * — so every entry becomes its own one-scheme "or" alternative. A `$ref`
+ * pointing at an undeclared scheme is kept (with `scheme` undefined),
+ * matching {@link resolveSecurity}'s render-don't-drop rule.
+ */
+export const resolveAsyncApiSecurity = (
+  entries: AsyncApiSecurityEntryLike[],
+  schemes: Record<string, SecuritySchemeLike> | undefined
+): OperationSecurity => {
+  const alternatives: ResolvedScheme[][] = [];
+  for (const entry of entries) {
+    if (!isSecurityEntryObject(entry)) {
+      continue;
+    }
+    const pointer = SECURITY_SCHEME_REF.exec(entry.$ref ?? "")?.groups?.name;
+    const name = pointer === undefined ? undefined : unescapePointer(pointer);
+    const inline = name === undefined && !isSpecString(entry.$ref);
+    const scheme = inline ? entry : schemes?.[name ?? ""];
+    alternatives.push([
+      {
+        key:
+          name ??
+          (isSpecString(entry.type) && entry.type !== ""
+            ? entry.type
+            : "security"),
+        scheme,
+        scopes:
+          inline && Array.isArray(entry.scopes)
+            ? entry.scopes.filter(
+                (scope): scope is string => typeof scope === "string"
+              )
+            : [],
+      },
+    ]);
+  }
+  return { alternatives, optional: false };
+};
+
 const capitalize = (text: string): string =>
   text.charAt(0).toUpperCase() + text.slice(1);
 
+/**
+ * Fixed labels for scheme types with no per-scheme variation. Covers both
+ * OpenAPI's types and the broker-auth types AsyncAPI adds; `http` is handled
+ * separately (its label depends on the scheme/bearerFormat fields).
+ */
+const TYPE_LABELS = new Map<string, string>([
+  ["X509", "X.509 certificate"],
+  ["apiKey", "API key"],
+  ["asymmetricEncryption", "Asymmetric encryption"],
+  ["gssapi", "SASL/GSSAPI"],
+  ["httpApiKey", "API key"],
+  ["mutualTLS", "Mutual TLS"],
+  ["oauth2", "OAuth2 access token"],
+  ["openIdConnect", "OpenID Connect token"],
+  ["plain", "SASL/PLAIN"],
+  ["scramSha256", "SASL/SCRAM-SHA-256"],
+  ["scramSha512", "SASL/SCRAM-SHA-512"],
+  ["symmetricEncryption", "Symmetric encryption"],
+  ["userPassword", "Username & password"],
+]);
+
 /** A short human label for a scheme row, e.g. `Bearer token` or `API key`. */
 export const schemeLabel = (resolved: ResolvedScheme): string => {
   const { scheme } = resolved;
-  switch (scheme?.type) {
-    case "http": {
-      const kind = (scheme.scheme ?? "").toLowerCase();
-      if (kind === "bearer") {
-        return scheme.bearerFormat
-          ? `Bearer token (${scheme.bearerFormat})`
-          : "Bearer token";
-      }
-      if (kind === "basic") {
-        return "Basic auth";
-      }
-      return kind ? `HTTP ${kind}` : "HTTP auth";
-    }
-    case "apiKey": {
-      return "API key";
+  if (scheme?.type === "http") {
+    const kind = (scheme.scheme ?? "").toLowerCase();
+    if (kind === "bearer") {
+      return scheme.bearerFormat
+        ? `Bearer token (${scheme.bearerFormat})`
+        : "Bearer token";
     }
-    case "oauth2": {
-      return "OAuth2 access token";
-    }
-    case "openIdConnect": {
-      return "OpenID Connect token";
-    }
-    case "mutualTLS": {
-      return "Mutual TLS";
-    }
-    default: {
-      // Unknown scheme ref: the component name is the best label available.
-      return resolved.key;
+    if (kind === "basic") {
+      return "Basic auth";
     }
+    return kind ? `HTTP ${kind}` : "HTTP auth";
   }
+  // Unknown scheme ref: the component name is the best label available.
+  return TYPE_LABELS.get(scheme?.type ?? "") ?? resolved.key;
 };
 
 /**
@@ -138,7 +210,8 @@ export const schemeCarrier = (
     case "openIdConnect": {
       return { in: "header", name: "Authorization" };
     }
-    case "apiKey": {
+    case "apiKey":
+    case "httpApiKey": {
       return { in: scheme.in ?? "header", name: scheme.name ?? resolved.key };
     }
     default: {