@lukoweb/apitogo 0.2.50 → 0.2.52

package/src/config/v2/gateway-reference.ts

@@ -18,7 +18,13 @@ export type ReferenceOptions = {
 };
 
 /** Header of the API key when the gateway does not say otherwise (same as the platform's OpenAPI export). */
-export const DEFAULT_KEY_HEADER = "Ocp-Apim-Subscription-Key";
+export const DEFAULT_KEY_HEADER = "X-API-Key";
+
+/**
+ * Operation extension naming the header a protected operation's key goes in. The API page's code samples read it
+ * (`createHttpSnippet`), so they show the header with a placeholder key.
+ */
+export const KEY_HEADER_EXTENSION = "x-apitogo-key-header";
 
 const METHODS = [
   "get",
@@ -175,10 +181,17 @@ export function buildReferenceSpec(
   else delete doc.components;
   // One requirement with both schemes means both are needed together.
   doc.security = Object.keys(requirement).length > 0 ? [requirement] : [];
-  for (const [, item, method] of operationsOf(paths)) {
+  for (const [path, item, method] of operationsOf(paths)) {
     const operation = item[method] as Json;
     if (Array.isArray(operation.security) && operation.security.length > 0)
       delete operation.security;
+    // The page's code samples add this header, so a copied sample works once the key is filled in (API-120).
+    if (
+      options.apiKeyRequired &&
+      !options.publicOperations.has(actionKey(method, path))
+    )
+      operation[KEY_HEADER_EXTENSION] = options.apiKeyHeader;
+    else delete operation[KEY_HEADER_EXTENSION];
   }
 
   return JSON.parse(hideOrigin(JSON.stringify(doc), options)) as Json;

package/src/config/v2/init.ts

@@ -59,7 +59,7 @@ title: Welcome
 
 # ${name}
 
-This page was created by \`apitogo init\`. Edit it, and add more \`.md\` or \`.mdx\` files next to it: each one becomes a page of your portal.
+Welcome to the ${name} developer portal. Here you will find guides, the API reference, and everything you need to get an API key and make your first call.
 `;
 }
 

package/src/config/v2/starter-landing.ts

@@ -9,15 +9,22 @@ export function starterLandingPage(options: {
 }): string {
   const name = JSON.stringify(options.name);
   const plansImport = options.withPlans
-    ? 'import { usePlansPreview } from "@lukoweb/apitogo-plugin-dev-portal-billing";\n'
+    ? 'import {\n  useGatewayCall,\n  usePlansPreview,\n} from "@lukoweb/apitogo-plugin-dev-portal-billing";\n'
     : "";
   const plansHook = options.withPlans
-    ? "  // The plans of the project's catalog: the same ones the pricing page shows.\n  const plans = usePlansPreview();\n\n"
+    ? "  // The plans of the project's catalog: the same ones the pricing page shows.\n  const plans = usePlansPreview();\n  // The real gateway address and key header, so the sample works when it is pasted with a key.\n  const gateway = useGatewayCall();\n\n"
     : "";
+  // Without the plans service the page cannot learn the gateway, so the sample names the platform's default header.
+  const sampleUrl = options.withPlans
+    ? '${gateway.baseUrl ?? "https://YOUR-GATEWAY"}'
+    : "https://YOUR-GATEWAY";
+  const sampleHeader = options.withPlans ? "${gateway.keyHeader}" : "X-API-Key";
   const plansSection = options.withPlans
     ? "      <PlansPreviewSection plans={plans} />\n"
     : "";
-  return `import {
+  return `// Your portal's home page. Edit this file (apitogo/portal/landing/LandingPage.tsx) to make it yours: everything
+// on it is public, so keep notes for yourself in comments like this one.
+import {
   ApiShowcaseSection,
   FeaturesSection,
   HeroSection,
@@ -47,8 +54,8 @@ ${plansHook}  return (
           {
             filename: "Call the API",
             language: "bash",
-            code: \`$ curl https://your-api.example.com/health \\\\
-  -H "x-api-key: YOUR_API_KEY"
+            code: \`$ curl ${sampleUrl}/health \\\\
+  -H "${sampleHeader}: YOUR_API_KEY"
 # { "status": "ok" }\`,
           },
         ]}
@@ -58,7 +65,7 @@ ${plansHook}  return (
           label: "What you get",
           title: "A developer portal that is ready on day one",
           description:
-            "Edit this page in apitogo/portal/landing/LandingPage.tsx to make it yours.",
+            "Docs, a live API reference, self-service API keys and clear plans, all in one place.",
         }}
         features={[
           {

package/src/config/v2/wrapper.ts

@@ -41,6 +41,18 @@ export function contentGlob(configDir: string, glob: string): string {
   return `${negated ? "!" : ""}/${CONTENT_LINK}/${relative}`;
 }
 
+/**
+ * A project file as the generated site root sees it: `content/<path in the project>`, which the build resolves against
+ * the site root. The generated config is imported by the portal's code, so an absolute path would end up in the public
+ * bundle (API-127). A file outside the project has no such path and keeps its absolute one.
+ */
+export function contentFile(configDir: string, file: string): string {
+  const relative = path.relative(configDir, file);
+  if (relative.startsWith("..") || path.isAbsolute(relative))
+    return file.split(path.sep).join("/");
+  return `${CONTENT_LINK}/${relative.split(path.sep).join("/")}`;
+}
+
 /** Capabilities of the plans service that put something on the console. Any one of them registers the plans plugin. */
 const PLANS_CONSOLE_CAPABILITIES = [
   "catalog",
@@ -77,6 +89,10 @@ export type PortalPlan = {
     billing?: string;
     /** Where the account pages link to: only places this portal has (hosted docs, an external docs site, the API page). */
     links?: { docs?: string; api?: string };
+    /** The header API users send their key in, from the gateway entry of services.json (API-120). */
+    keyHeader?: string;
+    /** The gateway's address, for code samples on the portal's pages. */
+    gatewayBaseUrl?: string;
   };
   /** Account pages. */
   userPanel: boolean;
@@ -259,6 +275,10 @@ export function planPortal(
       apiBaseUrl: plans.apiBaseUrl,
       keysApiBaseUrl: plans.keysApiBaseUrl,
       billing: plans.billing,
+      ...(gateway?.keyHeaderName ? { keyHeader: gateway.keyHeaderName } : {}),
+      ...(gateway?.baseUrl && serviceReady(gateway)
+        ? { gatewayBaseUrl: gateway.baseUrl }
+        : {}),
       links: {
         // Hosted docs are linked once their pages are known (see `buildPortalWorkspace`): there is no page to
         // name before that, and a guessed one was a 404 on every portal whose first page is not called `introduction`.
@@ -326,14 +346,14 @@ export function buildSiteConfig(
     },
     modules: {
       docs: { enabled: plan.docs },
-      // A custom home page (`portal.landing`) is served at `/`; the build imports the component from its absolute path.
+      // A custom home page (`portal.landing`) is served at `/`; the build imports the component through the content link.
       ...(portal?.landing
         ? {
             landing: {
               enabled: true,
               path: "/",
               layout: "landing",
-              page: portal.landing.split(path.sep).join("/"),
+              page: contentFile(resolved.configDir, portal.landing),
             },
           }
         : {}),

package/src/lib/plugins/openapi/util/createHttpSnippet.ts

@@ -1,135 +1,147 @@
-import { HTTPSnippet } from "@zudoku/httpsnippet";
-import type { OperationsFragmentFragment } from "../graphql/graphql.js";
-
-const toFormDataParams = (text?: string) => {
-  const stringify = (v: unknown) =>
-    typeof v === "string" ? v : JSON.stringify(v);
-
-  try {
-    const obj = text && JSON.parse(text);
-    if (typeof obj !== "object" || !obj) return [];
-
-    return Object.entries(obj).flatMap(([name, value]) => {
-      const values = Array.isArray(value) ? value : [value];
-      return values.map((v) => ({ name, value: stringify(v) }));
-    });
-  } catch {
-    return [];
-  }
-};
-
-export const createHttpSnippet = ({
-  operation,
-  selectedServer,
-  exampleBody,
-}: {
-  operation: OperationsFragmentFragment;
-  selectedServer: string;
-  exampleBody: {
-    mimeType: string;
-    text?: string;
-  };
-}) => {
-  const isMultipart =
-    exampleBody.mimeType === "multipart/form-data" ||
-    exampleBody.mimeType === "application/x-www-form-urlencoded";
-
-  const postData = isMultipart
-    ? {
-        mimeType: exampleBody.mimeType,
-        params: toFormDataParams(exampleBody.text),
-      }
-    : exampleBody;
-
-  return new HTTPSnippet({
-    method: operation.method.toUpperCase(),
-    url:
-      selectedServer + operation.path.replaceAll("{", ":").replaceAll("}", ""),
-    postData,
-    headers: [
-      ...(exampleBody.text
-        ? [{ name: "Content-Type", value: exampleBody.mimeType }]
-        : []),
-      ...(operation.parameters
-        ?.filter((p) => p.in === "header" && p.required === true)
-        .map((p) => ({
-          name: p.name,
-          value:
-            p.schema?.default ??
-            p.examples?.find((x) => x.value)?.value ??
-            (p.schema?.type === "string"
-              ? "<string>"
-              : p.schema?.type === "number" || p.schema?.type === "integer"
-                ? "<number>"
-                : p.schema?.type === "boolean"
-                  ? "<bool>"
-                  : "<value>"),
-        })) ?? []),
-    ],
-    queryString:
-      operation.parameters
-        ?.filter((p) => p.in === "query" && p.required === true)
-        .map((p) => ({
-          name: p.name,
-          value:
-            p.schema?.default ??
-            p.examples?.find((x) => x.value)?.value ??
-            (p.schema?.type === "string"
-              ? "<string>"
-              : p.schema?.type === "number" || p.schema?.type === "integer"
-                ? "<number>"
-                : p.schema?.type === "boolean"
-                  ? "<bool>"
-                  : "<value>"),
-        })) ?? [],
-    httpVersion: "",
-    cookies: [],
-    headersSize: 0,
-    bodySize: 0,
-  });
-};
-
-export const getConverted = (snippet: HTTPSnippet, option: string) => {
-  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
-  let converted: any;
-  switch (option) {
-    case "shell":
-      converted = snippet.convert("shell", "curl");
-      break;
-    case "js":
-      converted = snippet.convert("javascript", "fetch");
-      break;
-    case "python":
-      converted = snippet.convert("python", "requests");
-      break;
-    case "java":
-      converted = snippet.convert("java", "okhttp");
-      break;
-    case "go":
-      converted = snippet.convert("go", "native");
-      break;
-    case "csharp":
-      converted = snippet.convert("csharp", "httpclient");
-      break;
-    case "kotlin":
-      converted = snippet.convert("kotlin", "okhttp");
-      break;
-    case "objc":
-      converted = snippet.convert("objc", "nsurlsession");
-      break;
-    case "php":
-      converted = snippet.convert("php", "http2");
-      break;
-    case "ruby":
-      converted = snippet.convert("ruby");
-      break;
-    case "swift":
-      converted = snippet.convert("swift");
-      break;
-    default:
-      converted = snippet.convert("shell");
-      break;
-  }
-
-  return converted ? converted[0] : "";
-};
+import { HTTPSnippet } from "@zudoku/httpsnippet";
+import type { OperationsFragmentFragment } from "../graphql/graphql.js";
+
+/** Operation extension with the header a key goes in (same name as `KEY_HEADER_EXTENSION` in the CLI's config). */
+export const KEY_HEADER_EXTENSION = "x-apitogo-key-header";
+
+/** What a code sample shows where the visitor's key goes. */
+export const KEY_PLACEHOLDER = "YOUR_API_KEY";
+
+const toFormDataParams = (text?: string) => {
+  const stringify = (v: unknown) =>
+    typeof v === "string" ? v : JSON.stringify(v);
+
+  try {
+    const obj = text && JSON.parse(text);
+    if (typeof obj !== "object" || !obj) return [];
+
+    return Object.entries(obj).flatMap(([name, value]) => {
+      const values = Array.isArray(value) ? value : [value];
+      return values.map((v) => ({ name, value: stringify(v) }));
+    });
+  } catch {
+    return [];
+  }
+};
+
+export const createHttpSnippet = ({
+  operation,
+  selectedServer,
+  exampleBody,
+}: {
+  operation: OperationsFragmentFragment;
+  selectedServer: string;
+  exampleBody: {
+    mimeType: string;
+    text?: string;
+  };
+}) => {
+  const isMultipart =
+    exampleBody.mimeType === "multipart/form-data" ||
+    exampleBody.mimeType === "application/x-www-form-urlencoded";
+
+  const postData = isMultipart
+    ? {
+        mimeType: exampleBody.mimeType,
+        params: toFormDataParams(exampleBody.text),
+      }
+    : exampleBody;
+
+  const keyHeader = operation.extensions?.[KEY_HEADER_EXTENSION];
+
+  return new HTTPSnippet({
+    method: operation.method.toUpperCase(),
+    url:
+      selectedServer + operation.path.replaceAll("{", ":").replaceAll("}", ""),
+    postData,
+    headers: [
+      // The gateway's key header, on operations that need a key (set by the portal build, API-120).
+      ...(typeof keyHeader === "string" && keyHeader
+        ? [{ name: keyHeader, value: KEY_PLACEHOLDER }]
+        : []),
+      ...(exampleBody.text
+        ? [{ name: "Content-Type", value: exampleBody.mimeType }]
+        : []),
+      ...(operation.parameters
+        ?.filter((p) => p.in === "header" && p.required === true)
+        .map((p) => ({
+          name: p.name,
+          value:
+            p.schema?.default ??
+            p.examples?.find((x) => x.value)?.value ??
+            (p.schema?.type === "string"
+              ? "<string>"
+              : p.schema?.type === "number" || p.schema?.type === "integer"
+                ? "<number>"
+                : p.schema?.type === "boolean"
+                  ? "<bool>"
+                  : "<value>"),
+        })) ?? []),
+    ],
+    queryString:
+      operation.parameters
+        ?.filter((p) => p.in === "query" && p.required === true)
+        .map((p) => ({
+          name: p.name,
+          value:
+            p.schema?.default ??
+            p.examples?.find((x) => x.value)?.value ??
+            (p.schema?.type === "string"
+              ? "<string>"
+              : p.schema?.type === "number" || p.schema?.type === "integer"
+                ? "<number>"
+                : p.schema?.type === "boolean"
+                  ? "<bool>"
+                  : "<value>"),
+        })) ?? [],
+    httpVersion: "",
+    cookies: [],
+    headersSize: 0,
+    bodySize: 0,
+  });
+};
+
+export const getConverted = (snippet: HTTPSnippet, option: string) => {
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+  let converted: any;
+  switch (option) {
+    case "shell":
+      converted = snippet.convert("shell", "curl");
+      break;
+    case "js":
+      converted = snippet.convert("javascript", "fetch");
+      break;
+    case "python":
+      converted = snippet.convert("python", "requests");
+      break;
+    case "java":
+      converted = snippet.convert("java", "okhttp");
+      break;
+    case "go":
+      converted = snippet.convert("go", "native");
+      break;
+    case "csharp":
+      converted = snippet.convert("csharp", "httpclient");
+      break;
+    case "kotlin":
+      converted = snippet.convert("kotlin", "okhttp");
+      break;
+    case "objc":
+      converted = snippet.convert("objc", "nsurlsession");
+      break;
+    case "php":
+      converted = snippet.convert("php", "http2");
+      break;
+    case "ruby":
+      converted = snippet.convert("ruby");
+      break;
+    case "swift":
+      converted = snippet.convert("swift");
+      break;
+    default:
+      converted = snippet.convert("shell");
+      break;
+  }
+
+  return converted ? converted[0] : "";
+};