blume 2.1.0 → 2.1.1

package/src/components/openapi/GraphqlOperation.astro

@@ -19,10 +19,12 @@ import {
   exampleVariables,
   graphqlPlaygroundModel,
   graphqlRoutes,
+  graphqlSecurity,
 } from "./graphql-helpers.ts";
 import { buildRequest, defaultValues } from "./request.ts";
 import { languageSamplePanels } from "./sample-panels.ts";
 import { sampleLanguages } from "./snippets.ts";
+import Authorization from "./Authorization.astro";
 import Description from "./Description.astro";
 import GraphqlChip from "./GraphqlChip.astro";
 import GraphqlFieldsTable from "./GraphqlFieldsTable.astro";
@@ -107,6 +109,7 @@ const responsePanels =
     : [];
 
 const returnRoute = field ? routes.get(field.type.name) : undefined;
+const security = spec ? graphqlSecurity(spec) : undefined;
 ---
 
 {
@@ -134,6 +137,7 @@ const returnRoute = field ? routes.get(field.type.name) : undefined;
               Deprecated: <span set:text={field.deprecationReason} />
             </p>
           )}
+          {security && <Authorization security={security} />}
           <GraphqlFieldsTable
             routes={routes}
             rows={field.args}
@@ -169,6 +173,7 @@ const returnRoute = field ? routes.get(field.type.name) : undefined;
                 model={model}
                 operation={id}
                 proxy={spec.playground.proxy}
+                proxyConfig="graphql"
                 slug={spec.slug}
               />
             )}

package/src/components/openapi/Operation.astro

@@ -131,6 +131,10 @@ const params = mergeParameters(
 const requestBody = operation?.requestBody
   ? resolveComponentRef(operation.requestBody, components, "requestBodies")
   : undefined;
+// A request body table leaves out `readOnly` fields. A webhook's or
+// callback's body is a request the API sends, so it reads like a response
+// (and like its payload example): `readOnly` fields in, `writeOnly` out.
+const bodyDirection = isWebhook ? "response" : "request";
 const responses = Object.fromEntries(
   Object.entries(operation?.responses ?? {}).map(([status, response]) => [
     status,
@@ -178,6 +182,8 @@ interface CallbackEntry {
   method: string;
   name: string;
   operation: FullOperation;
+  /** The callback path item's own parameters, which each method inherits. */
+  pathParameters?: ParameterLike[];
 }
 
 // Callbacks: for each named callback (resolved through
@@ -202,6 +208,10 @@ const callbacks: CallbackEntry[] = Object.entries(
               // SAFETY: a path item's method entry is an operation object; the
               // object check above guards a spec that put a scalar there.
               operation: entry as FullOperation,
+              // SAFETY: the object check above passed, and a path item's
+              // `parameters` is a parameter list, which `mergeParameters`
+              // reads the way it reads an operation's.
+              pathParameters: (item as PathItemLike).parameters,
             },
           ]
         : [];
@@ -209,8 +219,13 @@ const callbacks: CallbackEntry[] = Object.entries(
   });
 });
 
-/** A callback's request body and responses, `$ref`s resolved. */
+/** A callback's parameters, request body, and responses, `$ref`s resolved. */
 const callbackParts = (entry: CallbackEntry) => ({
+  parameters: mergeParameters(
+    entry.pathParameters,
+    entry.operation.parameters,
+    components
+  ),
   requestBody: entry.operation.requestBody
     ? resolveComponentRef(entry.operation.requestBody, components, "requestBodies")
     : undefined,
@@ -253,6 +268,7 @@ const callbackParts = (entry: CallbackEntry) => ({
           <ParametersTable parameters={params} schemas={schemas} />
           {requestBody && (
             <RequestBody
+              direction={bodyDirection}
               expandAll={spec.expandSchemas}
               requestBody={requestBody}
               schemas={schemas}
@@ -298,8 +314,14 @@ const callbackParts = (entry: CallbackEntry) => ({
                           text={entry.operation.description}
                         />
                       )}
+                      <ParametersTable
+                        level={4}
+                        parameters={parts.parameters}
+                        schemas={schemas}
+                      />
                       {parts.requestBody && (
                         <RequestBody
+                          direction="response"
                           expandAll={spec.expandSchemas}
                           level={4}
                           requestBody={parts.requestBody}
@@ -339,6 +361,7 @@ const callbackParts = (entry: CallbackEntry) => ({
                 model={model}
                 operation={id}
                 proxy={spec.playground.proxy}
+                proxyConfig="openapi"
                 slug={spec.slug}
               />
             )}

package/src/components/openapi/ParametersTable.astro

@@ -2,6 +2,7 @@
 import Description from "./Description.astro";
 import {
   constraints,
+  parameterDescription,
   resolveSchema,
   type SchemaLike,
   typeLabel,
@@ -19,9 +20,11 @@ interface ParamLike {
 interface Props {
   parameters: ParamLike[];
   schemas: Record<string, SchemaLike>;
+  /** The headings' level: 2 on an operation, deeper inside a callback. */
+  level?: number;
 }
 
-const { parameters, schemas } = Astro.props;
+const { parameters, schemas, level = 2 } = Astro.props;
 
 const SECTIONS: { in: string; title: string }[] = [
   { in: "path", title: "Path parameters" },
@@ -42,7 +45,7 @@ const groups = SECTIONS.map((section) => ({
   groups.map((group) => (
     <section class="mt-6">
       <div
-        aria-level="2"
+        aria-level={level}
         class="mb-2 font-semibold text-foreground text-sm"
         role="heading"
       >
@@ -54,6 +57,7 @@ const groups = SECTIONS.map((section) => ({
           const type = param.schema ? typeLabel(param.schema) : "string";
           const limits = constraints(resolved);
           const enumValues = Array.isArray(resolved.enum) ? resolved.enum : null;
+          const description = parameterDescription(param, schemas);
           return (
             <div class="border-border border-t py-4 first:border-t-0">
               <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
@@ -70,8 +74,8 @@ const groups = SECTIONS.map((section) => ({
                   </span>
                 )}
               </div>
-              {param.description && (
-                <Description class="mt-2 text-muted-foreground text-sm" text={param.description} />
+              {description && (
+                <Description class="mt-2 text-muted-foreground text-sm" text={description} />
               )}
               {limits.length > 0 && (
                 <div class="mt-2 text-muted-foreground text-xs">

package/src/components/openapi/Playground.astro

@@ -17,12 +17,17 @@ interface Props {
   model: PlaygroundModel;
   /** Proxy route for the send, or false to fetch the API directly. */
   proxy: string | false;
+  /**
+   * Where this panel's proxy is configured, which the CORS message names:
+   * an `openapi()` or `graphql()` reference, or `api` for hand-written pages.
+   */
+  proxyConfig: "api" | "graphql" | "openapi";
   /** Spec slug + operation key form the per-operation localStorage key. */
   slug: string;
   operation: string;
 }
 
-const { model, proxy, slug, operation } = Astro.props;
+const { model, proxy, proxyConfig, slug, operation } = Astro.props;
 
 // The built-in proxy route carries the site `basePath` but, like every
 // internal URL in the spec data, not `deployment.base`; `withMountedBase`
@@ -53,6 +58,7 @@ const CHECKBOX_ROW =
 <blume-playground
   class="mb-6 block"
   data-proxy={proxyUrl}
+  data-proxy-config={proxyConfig}
   data-storage-key={`blume-playground:${slug}:${operation}`}
 >
   <script

package/src/components/openapi/RequestBody.astro

@@ -1,6 +1,7 @@
 ---
 import Description from "./Description.astro";
 import type { SchemaLike } from "./helpers.ts";
+import type { SchemaDirection } from "./schema-tree.ts";
 import SchemaTable from "./SchemaTable.astro";
 
 interface MediaTypeLike {
@@ -19,9 +20,20 @@ interface Props {
   expandAll?: boolean;
   /** The heading's level: 2 on an operation, deeper inside a callback. */
   level?: number;
+  /**
+   * `request` (the default) leaves out `readOnly` fields; a webhook or
+   * callback, which the API sends, reads like a response instead.
+   */
+  direction?: SchemaDirection;
 }
 
-const { requestBody, schemas, expandAll = false, level = 2 } = Astro.props;
+const {
+  requestBody,
+  schemas,
+  expandAll = false,
+  level = 2,
+  direction = "request",
+} = Astro.props;
 
 const entries = Object.entries(requestBody.content ?? {});
 const chosen = entries.find(([type]) => type.includes("json")) ?? entries[0];
@@ -53,6 +65,11 @@ const schema = chosen?.[1]?.schema ?? {};
     )
   }
   <div class="mt-3">
-    <SchemaTable expandAll={expandAll} schema={schema} schemas={schemas} />
+    <SchemaTable
+      direction={direction}
+      expandAll={expandAll}
+      schema={schema}
+      schemas={schemas}
+    />
   </div>
 </section>

package/src/components/openapi/Responses.astro

@@ -64,6 +64,7 @@ const items = Object.entries(responses);
               {schema && (
                 <div class="mt-3">
                   <SchemaTable
+                    direction="response"
                     expandAll={expandAll}
                     schema={schema}
                     schemas={schemas}

package/src/components/openapi/SchemaTable.astro

@@ -1,6 +1,10 @@
 ---
 import type { SchemaLike } from "./helpers.ts";
-import { type SchemaNode, schemaTree } from "./schema-tree.ts";
+import {
+  type SchemaDirection,
+  type SchemaNode,
+  schemaTree,
+} from "./schema-tree.ts";
 import SchemaProperty from "./SchemaProperty.astro";
 
 interface Props {
@@ -10,13 +14,21 @@ interface Props {
   node?: SchemaNode;
   schemas: Record<string, SchemaLike>;
   expandAll?: boolean;
+  /** Which way the data travels, which decides the fields left out. */
+  direction?: SchemaDirection;
 }
 
-const { schema = {}, node: planned, schemas, expandAll = false } = Astro.props;
+const {
+  schema = {},
+  node: planned,
+  schemas,
+  expandAll = false,
+  direction,
+} = Astro.props;
 
 // The whole tree is planned once, at the top-level table, so that which named
 // schemas expand is decided for the tree as a whole (see `schema-tree.ts`).
-const node = planned ?? schemaTree(schema, schemas);
+const node = planned ?? schemaTree(schema, schemas, direction);
 ---
 
 {

package/src/components/openapi/async-snippets.ts

@@ -25,7 +25,12 @@ export interface MessageSample {
   address: string;
   /** Example payload value (undefined when none could be derived). */
   payload?: unknown;
-  /** First server the channel is available on, if any. */
+  /** Example Kafka message key, when the message's binding declares one. */
+  key?: string;
+  /**
+   * First server the channel is available on, if any, its `security` entries
+   * resolved to scheme objects.
+   */
   server?: AsyncApiServerObject;
 }
 
@@ -98,12 +103,63 @@ const webSocketSnippet = (sample: MessageSample): string => {
   ].join("\n");
 };
 
+/** librdkafka's `sasl.mechanisms` value for each AsyncAPI SASL scheme type. */
+const SASL_MECHANISMS = new Map([
+  ["gssapi", "GSSAPI"],
+  ["plain", "PLAIN"],
+  ["scramSha256", "SCRAM-SHA-256"],
+  ["scramSha512", "SCRAM-SHA-512"],
+]);
+
+/**
+ * The `-X` properties kcat hands librdkafka to reach the server: TLS for
+ * `kafka-secure`, and the first SASL scheme the server declares, with its
+ * credentials read from the environment (Kerberos brings its own).
+ */
+const kafkaSecurityFlags = (server?: AsyncApiServerObject): string[] => {
+  const tls = server?.protocol?.toLowerCase() === "kafka-secure";
+  const mechanism = (server?.security ?? [])
+    .map((entry) => SASL_MECHANISMS.get(String(entry?.type)))
+    .find((value) => value !== undefined);
+  if (mechanism === undefined) {
+    return tls ? ["-X security.protocol=SSL"] : [];
+  }
+  const flags = [
+    `-X security.protocol=${tls ? "SASL_SSL" : "SASL_PLAINTEXT"}`,
+    `-X sasl.mechanisms=${mechanism}`,
+  ];
+  if (mechanism !== "GSSAPI") {
+    flags.push(
+      '-X sasl.username="$KAFKA_USERNAME"',
+      '-X sasl.password="$KAFKA_PASSWORD"'
+    );
+  }
+  return flags;
+};
+
+/**
+ * The separator between key and value: kcat splits each produced line at its
+ * first `|`, and prints consumed keys before one.
+ */
+const KEY_DELIMITER = "|";
+
 const kcatSnippet = (sample: MessageSample): string => {
   const broker = sample.server?.host ?? "localhost:9092";
-  const base = `kcat -b ${shellQuote(broker)} -t ${shellQuote(sample.address)}`;
-  return sample.action === "receive"
-    ? `echo ${shellQuote(payloadInline(sample))} | ${base} -P`
-    : `${base} -C`;
+  const mode = sample.action === "receive" ? "-P" : "-C";
+  const keyed =
+    sample.key === undefined ? "" : ` -K ${shellQuote(KEY_DELIMITER)}`;
+  const command = [
+    `kcat -b ${shellQuote(broker)} -t ${shellQuote(sample.address)} ${mode}${keyed}`,
+    ...kafkaSecurityFlags(sample.server),
+  ].join(" \\\n  ");
+  if (sample.action !== "receive") {
+    return command;
+  }
+  const line =
+    sample.key === undefined
+      ? payloadInline(sample)
+      : `${sample.key}${KEY_DELIMITER}${payloadInline(sample)}`;
+  return `echo ${shellQuote(line)} | ${command}`;
 };
 
 const mosquittoSnippet = (sample: MessageSample): string => {

package/src/components/openapi/async.ts

@@ -8,6 +8,8 @@ import type {
 } from "../../openapi/asyncapi.ts";
 import type { ParameterLike, SchemaLike } from "./helpers.ts";
 import { resolveComponentRef } from "./helpers.ts";
+import type { OperationSecurity, SecuritySchemeLike } from "./security.ts";
+import { resolveAsyncApiSecurity } from "./security.ts";
 
 /**
  * Runtime helpers for the AsyncAPI components — the async counterpart of
@@ -239,32 +241,61 @@ export const channelParameters = (
 
 const SERVER_REF = /^#\/servers\/(?<name>[^/]+)$/u;
 
+/** A server paired with its key under the document's `servers`. */
+export interface NamedServer {
+  name: string;
+  server: AsyncApiServerObject;
+}
+
 /**
- * The servers a channel is available on: its `servers` refs when declared,
- * else every server the document declares (the spec's default).
+ * The servers a channel is available on, by name: its `servers` refs when
+ * declared, else every server the document declares (the spec's default).
  */
-export const channelServers = (
+export const namedChannelServers = (
   channel: AsyncApiChannelObject | undefined,
   document: AsyncApiDocument
-): AsyncApiServerObject[] => {
+): NamedServer[] => {
   const all = document.servers ?? {};
   const refs = channel?.servers;
   if (!Array.isArray(refs) || refs.length === 0) {
-    return Object.values(all).filter(isObject);
+    return Object.entries(all).flatMap(([name, server]) =>
+      isObject(server) ? [{ name, server }] : []
+    );
   }
-  const servers: AsyncApiServerObject[] = [];
+  const servers: NamedServer[] = [];
   for (const ref of refs) {
-    const name = SERVER_REF.exec(
+    const pointer = 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);
+    const name = pointer === undefined ? undefined : unescapePointer(pointer);
+    const server = name === undefined ? undefined : all[name];
+    if (name !== undefined && isObject(server)) {
+      servers.push({ name, server });
     }
   }
   return servers;
 };
 
+/**
+ * A server's `security` entries with their `$ref`s into
+ * `components.securitySchemes` resolved (non-objects dropped), for the
+ * samples, which read the scheme off the server they're built from.
+ */
+export const resolvedServerSecurity = (
+  server: AsyncApiServerObject,
+  components?: Components
+): AsyncApiRefLike[] =>
+  (Array.isArray(server.security) ? server.security : [])
+    .filter(isObject)
+    .map((entry) => resolveComponentRef(entry, components, "securitySchemes"));
+
+/** The servers a channel is available on; see {@link namedChannelServers}. */
+export const channelServers = (
+  channel: AsyncApiChannelObject | undefined,
+  document: AsyncApiDocument
+): AsyncApiServerObject[] =>
+  namedChannelServers(channel, document).map(({ server }) => server);
+
 /** A protocol-keyed `bindings` map, whatever object it sits on. */
 type BindingMap = Record<string, AsyncApiSpecValue>;
 
@@ -291,6 +322,34 @@ export const resolveBindings = (
   return isObject(target) ? target : undefined;
 };
 
+/** The `kafka` object of a bindings map, a `$ref`'d map resolved. */
+const kafkaBinding = (
+  bindings: BindingMap | undefined,
+  components?: Components
+): Record<string, AsyncApiSpecValue> | undefined => {
+  const kafka = resolveBindings(bindings, components)?.kafka;
+  return isObject(kafka) ? kafka : undefined;
+};
+
+/**
+ * A Kafka channel binding's `topic`, which names the topic when it differs
+ * from the channel address. The samples produce to and consume from it.
+ */
+export const kafkaTopic = (
+  channel: AsyncApiChannelObject | undefined,
+  components?: Components
+): string | undefined => {
+  const topic = kafkaBinding(channel?.bindings, components)?.topic;
+  return isString(topic) && topic !== "" ? topic : undefined;
+};
+
+/** The schema of a message's Kafka key (its `kafka` binding's `key`). */
+export const kafkaKeySchema = (
+  message: AsyncApiMessageLike | undefined,
+  components?: Components
+): SchemaLike | undefined =>
+  schemaOf(kafkaBinding(message?.bindings, components)?.key);
+
 /** Normalize protocol spellings onto the binding key they document. */
 const PROTOCOL_ALIASES = {
   "kafka-secure": "kafka",
@@ -326,35 +385,70 @@ export const protocolOf = (
 };
 
 /**
- * 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.
+ * The security an operation renders: 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. Each server's list stands alone, though: when the servers
+ * disagree (a production cluster behind SASL beside a local broker with no
+ * security), a scheme only some servers declare names them, and
+ * `unauthenticatedServers` lists the ones that declare none, rather than one
+ * server's scheme reading as required on all of them.
  */
-export const asyncApiSecurityEntries = (
+export const asyncApiSecurity = (
   operation: AsyncApiOperationObject | undefined,
-  servers: AsyncApiServerObject[]
-): AsyncApiRefLike[] => {
+  servers: NamedServer[],
+  schemes: Record<string, SecuritySchemeLike> | undefined
+): OperationSecurity => {
   if (Array.isArray(operation?.security)) {
-    return operation.security;
+    return resolveAsyncApiSecurity(operation.security, schemes);
   }
-  const entries: AsyncApiRefLike[] = [];
-  const seen = new Set<string>();
-  for (const server of servers) {
-    for (const entry of server.security ?? []) {
-      if (!isObject(entry)) {
+  const entries: { entry: AsyncApiRefLike; servers: string[] }[] = [];
+  const byRef = new Map<string, string[]>();
+  const unauthenticated: string[] = [];
+  for (const { name, server } of servers) {
+    const declared = Array.isArray(server.security)
+      ? server.security.filter(isObject)
+      : [];
+    if (declared.length === 0) {
+      unauthenticated.push(name);
+    }
+    for (const entry of declared) {
+      const shared = isString(entry.$ref) ? byRef.get(entry.$ref) : undefined;
+      if (shared) {
+        shared.push(name);
         continue;
       }
+      const names = [name];
       if (isString(entry.$ref)) {
-        if (seen.has(entry.$ref)) {
-          continue;
-        }
-        seen.add(entry.$ref);
+        byRef.set(entry.$ref, names);
       }
-      entries.push(entry);
+      entries.push({ entry, servers: names });
     }
   }
-  return entries;
+  const agree =
+    entries.length === 0 ||
+    (unauthenticated.length === 0 &&
+      entries.every((item) => item.servers.length === servers.length));
+  if (agree) {
+    return resolveAsyncApiSecurity(
+      entries.map(({ entry }) => entry),
+      schemes
+    );
+  }
+  return {
+    // A scheme every server declares needs no server list of its own.
+    alternatives: entries.map(({ entry, servers: names }) =>
+      resolveAsyncApiSecurity([entry], schemes)
+        .alternatives.flat()
+        .map((resolved) =>
+          names.length === servers.length
+            ? resolved
+            : { ...resolved, servers: names }
+        )
+    ),
+    optional: false,
+    unauthenticatedServers: unauthenticated,
+  };
 };
 
 /** One protocol's binding fields, ready for a key/value table. */

package/src/components/openapi/graphql-helpers.ts

@@ -10,8 +10,11 @@ import {
   isGraphqlOperationKind,
 } from "../../openapi/graphql.ts";
 import type { ApiSpecData } from "../../openapi/model.ts";
+import { endpointSecurity } from "../content/api-page.ts";
 import type { SpecValue } from "./helpers.ts";
+import { playgroundAuth } from "./operation-model.ts";
 import type { PlaygroundModel } from "./request.ts";
+import type { OperationSecurity } from "./security.ts";
 
 /**
  * Build-time logic behind the GraphQL reference pages: the generated example
@@ -67,9 +70,10 @@ const isComposite = (document: GraphqlDocument, name: string): boolean => {
 
 /**
  * A valid selection set for a composite type, or undefined for leaves: every
- * scalar/enum field, plus nested composites while `depth` allows. A composite
- * with nothing selectable at this depth falls back to `__typename`, which is
- * legal on any composite — the set must never come out empty.
+ * scalar/enum field, plus nested composites while `depth` allows, deprecated
+ * fields left out so the example doesn't teach them. A composite with nothing
+ * selectable at this depth falls back to `__typename`, which is legal on any
+ * composite — the set must never come out empty.
  */
 export const selectionSet = (
   document: GraphqlDocument,
@@ -85,10 +89,12 @@ export const selectionSet = (
   }
   const selections: GraphqlSelection[] = [];
   for (const field of type.fields ?? []) {
-    // A field with an argument that must be supplied — non-null and no
-    // default — can't ride an example selection; there is nothing valid to
-    // fill it with inline. A defaulted non-null argument is omittable.
+    // A deprecated field stays out of the example. So does a field with an
+    // argument that must be supplied — non-null and no default: there is
+    // nothing valid to fill it with inline. A defaulted non-null argument is
+    // omittable.
     if (
+      field.deprecationReason !== undefined ||
       field.args.some(
         (arg) => arg.type.display.endsWith("!") && arg.default === undefined
       )
@@ -189,10 +195,14 @@ const sampleForRef = (
   if (type?.kind === "enum") {
     named = type.enumValues?.[0]?.name ?? null;
   } else if (type?.kind === "input" && depth > 0) {
+    // A field with a default starts at it, the value a client leaving it
+    // out gets.
     named = Object.fromEntries(
       (type.inputFields ?? []).map((field) => [
         field.name,
-        sampleForRef(document, field.type, depth - 1),
+        field.defaultValue === undefined
+          ? sampleForRef(document, field.type, depth - 1)
+          : field.defaultValue,
       ])
     );
   } else if (type?.kind === "input") {
@@ -203,7 +213,10 @@ const sampleForRef = (
   return wrapLists(ref.display, named);
 };
 
-/** Example `variables` for a root field's arguments; undefined when it has none. */
+/**
+ * Example `variables` for a root field's arguments, each starting at its
+ * declared default when it has one; undefined when it has none.
+ */
 export const exampleVariables = (
   document: GraphqlDocument,
   field: GraphqlField
@@ -212,7 +225,9 @@ export const exampleVariables = (
     ? Object.fromEntries(
         field.args.map((arg) => [
           arg.name,
-          sampleForRef(document, arg.type, VARIABLE_DEPTH),
+          arg.defaultValue === undefined
+            ? sampleForRef(document, arg.type, VARIABLE_DEPTH)
+            : arg.defaultValue,
         ])
       )
     : undefined;
@@ -271,19 +286,27 @@ export const exampleResponse = (
   return { data };
 };
 
+/**
+ * The security every operation of a GraphQL reference enforces: its `auth`
+ * option, read the way a hand-written endpoint reads the site's `api.auth`.
+ */
+export const graphqlSecurity = (spec: ApiSpecData): OperationSecurity =>
+  endpointSecurity(undefined, spec.auth);
+
 /**
  * The playground/request model for one GraphQL operation: a plain POST whose
  * JSON body carries the query and variables. Reusing `PlaygroundModel` means
  * the OpenAPI playground UI, its client module, and `buildRequest` all work
- * unchanged — the samples show byte-for-byte what the Send button transmits.
+ * unchanged — the samples show byte-for-byte what the Send button transmits,
+ * the configured `auth` credential included.
  */
 export const graphqlPlaygroundModel = (
   spec: ApiSpecData,
   query: string,
   variables?: GraphqlSampleObject
 ): PlaygroundModel => ({
-  auth: [],
-  authOptional: true,
+  auth: playgroundAuth(graphqlSecurity(spec)),
+  authOptional: false,
   body: {
     contentType: "application/json",
     example: JSON.stringify(