@lukoweb/apitogo 0.2.54 → 0.2.57

package/docs/configuration/api-reference.md

@@ -1,397 +1,98 @@
----
-title: API Reference
-sidebar_icon: square-library
-description:
-  Learn how to configure the `apis` setting in APIToGo to generate API reference documentation from
-  OpenAPI files, including file and URL references, versioning, customization options, and OpenAPI
-  extensions.
----
-
-The `apis` configuration setting in the [APIToGo Configuration](./overview.md) file allows you to
-specify the OpenAPI document that you want to use to generate your API reference documentation.
-
-There are multiple ways to reference an API file in the configuration including using a URL or a
-local file path. The OpenAPI document can be in either JSON or YAML format.
-
-## File Reference
-
-You can reference a local OpenAPI document by setting the `type` to `file` and providing the path to
-the file.
-
-```ts title=config
-const config = {
-  // ...
-  apis: {
-    type: "file",
-    input: "./openapi.json", // Supports JSON and YAML files (ex. openapi.yaml)
-    path: "/api",
-  },
-  // ...
-};
-```
-
-## URL Reference
-
-:::danger{title="Recommendation"}
-
-We strongly recommend using `type: "file"` for your OpenAPI schemas. When using URL based
-references, all schema processing occurs at runtime in the browser. This can cause noticeable
-performance issues with large OpenAPI documents and some features may not be fully supported due to
-the added complexity of runtime processing.
-
-:::
-
-If your OpenAPI document is accessible elsewhere via URL you can use this configuration, changing
-the `input` value to the URL of your own OpenAPI document (you can use the Rick & Morty API document
-if you want to test and play around):
-
-```ts title=config
-const config = {
-  // ...
-  apis: {
-    type: "url",
-    input: "https://petstore3.swagger.io/api/v3/openapi.json",
-    path: "/api",
-  },
-  // ...
-};
-```
-
-:::caution{title="CORS Policy"}
-
-If you are using a URL to reference your OpenAPI document, you may need to ensure that the server
-hosting the document has the correct CORS policy in place to allow the APIToGo site to access it.
-
-:::
-
-## Versioning
-
-### File-based Versioning
-
-When using `type: "file"`, you can provide an array of file paths to create versioned API
-documentation. Version metadata is automatically extracted from each OpenAPI schema at build time:
-
-```ts title=config
-const config = {
-  apis: {
-    type: "file",
-    input: [
-      // Order of the array determines the order of the versions
-      "./openapi-v2.json",
-      "./openapi-v1.json",
-    ],
-    path: "/api",
-  },
-};
-```
-
-If you need to override version metadata, you can specify it explicitly:
-
-```ts title=config
-const config = {
-  apis: {
-    type: "file",
-    input: [
-      // Order of the array determines the order of the versions
-      {
-        path: "v2",
-        label: "Version 2.0",
-        input: "./openapi-v2.json",
-      },
-      {
-        path: "v1",
-        label: "Version 1.0",
-        input: "./openapi-v1.json",
-      },
-    ],
-    path: "/api",
-  },
-};
-```
-
-You can specify:
-
-- `input`: Path to the OpenAPI document (required)
-- `path`: Version identifier used in the URL path (e.g., `/api/v2`)
-- `label`: Optional display name for the version selector
-
-You can also mix strings and objects in the array - use strings for defaults and objects when you
-need to customize:
-
-```ts title=config
-const config = {
-  apis: {
-    type: "file",
-    input: [
-      {
-        path: "latest",
-        label: "Latest (2.0)",
-        input: "./openapi-v2.json",
-      },
-      "./openapi-v1.json", // Uses info.version from the document
-    ],
-    path: "/api",
-  },
-};
-```
-
-### Splitting a Single Schema
-
-If you have one schema containing multiple API versions (e.g. `/v1/...` and `/v2/...` paths), you
-can split it into separate versions by appending query parameters to the input path:
-
-```ts title=config
-const config = {
-  apis: {
-    type: "file",
-    input: ["openapi.json?prefix=/v2", "openapi.json?prefix=/v1"],
-    path: "/api",
-  },
-};
-```
-
-The query parameters are passed to [schema processors](../guides/processors) via the `params`
-argument, where you can filter the schema based on their values. See
-[Using Query Parameters to Split Schemas](../guides/processors#using-query-parameters-to-split-schemas)
-for a full example.
-
-### URL-based Versioning
-
-When using `type: "url"`, you can provide an array of version configurations. Since URL-based
-schemas cannot be processed at build time, you must explicitly specify the version identifier and
-optional label:
-
-```ts title=config
-const config = {
-  apis: {
-    type: "url",
-    input: [
-      {
-        path: "v2",
-        label: "Version 2.0",
-        input: "https://api.example.com/openapi-v2.json",
-      },
-      {
-        path: "v1",
-        label: "Version 1.0",
-        input: "https://api.example.com/openapi-v1.json",
-      },
-    ],
-    path: "/api",
-  },
-};
-```
-
-Each URL version object requires:
-
-- `path`: Version identifier used in the URL path (e.g., `/api/v2`)
-- `input`: URL to the OpenAPI document
-- `label`: Optional display name for the version selector (defaults to `path` if not provided)
-
-## Options
-
-The `options` field allows you to customize the API reference behavior:
-
-```ts title=config
-const config = {
-  apis: {
-    type: "file",
-    input: "./openapi.json",
-    path: "/api",
-    options: {
-      examplesLanguage: "shell", // Default language for code examples
-      supportedLanguages: [
-        { label: "cURL", language: "shell" },
-        { label: "JavaScript", language: "javascript" },
-      ],
-      disablePlayground: false, // Disable the interactive API playground
-      disableSidecar: false, // Disable the sidecar completely
-      showVersionSelect: "if-available", // Control version selector visibility
-      expandAllTags: true, // Control initial expanded state of tag categories
-      showInfoPage: true, // Show API information page as the index route
-      schemaDownload: {
-        enabled: true, // Enable schema download button
-      },
-    },
-  },
-};
-```
-
-Available options:
-
-- `examplesLanguage`: Set default language for code examples
-- `supportedLanguages`: Array of language options for code examples. Each option has `label`
-  (display name) and `language` (code identifier)
-- `disablePlayground`: Disable the interactive API playground globally
-- `disableSidecar`: Disable the sidecar panel completely
-- `showVersionSelect`: Control version selector visibility
-  - `"if-available"`: Show version selector only when multiple versions exist (default)
-  - `"always"`: Always show version selector (disabled if only one version)
-  - `"hide"`: Never show version selector
-- `expandAllTags`: Control initial expanded state of tag categories (default: `true`)
-- `showInfoPage`: Show the API information page as the index route (default: `true`). When disabled,
-  navigating to the API root redirects to the first tag instead
-- `schemaDownload`: Enable schema download functionality. When enabled, displays a button allowing
-  users to download the OpenAPI schema, copy it to clipboard, or open in a new tab.
-  - `enabled`: Enable or disable the schema download button
-- `transformExamples`: Function to transform request/response examples before rendering. See
-  [Transforming Examples](../guides/transforming-examples.md) for detailed usage
-- `generateCodeSnippet`: Function to generate custom code snippets for the API playground. See
-  [Advanced Configuration](#advanced-configuration) below
-
-## Default Options
-
-Instead of setting options for each API individually, you can use `defaults.apis` to set global
-defaults that apply to all APIs:
-
-```ts title=config
-const config = {
-  defaults: {
-    apis: {
-      examplesLanguage: "shell", // Default language for code examples
-      disablePlayground: false, // Disable the interactive API playground
-      disableSidecar: false, // Disable the sidecar completely
-      showVersionSelect: "if-available", // Control version selector visibility
-      expandAllTags: false, // Control initial expanded state of tag categories
-      showInfoPage: true, // Show API information page as the index route
-      schemaDownload: {
-        enabled: true, // Enable schema download button
-      },
-    },
-  },
-  apis: {
-    type: "file",
-    input: "./openapi.json",
-    path: "/api",
-  },
-};
-```
-
-Individual API options will override these defaults when specified.
-
-## AI Assistants
-
-The schema download dropdown includes AI assistant options (Claude, ChatGPT) by default. You can
-customize or disable these using the top-level `aiAssistants` configuration. See
-[AI Assistants](./ai-assistants.md) for full documentation.
-
-## Advanced Configuration
-
-### Custom Code Snippets
-
-Use `generateCodeSnippet` to generate custom code snippets instead of the default HTTP examples.
-This is useful when you want to show SDK usage or language-specific implementations.
-
-```tsx title=config
-const config: ApitogoConfig = {
-  apis: {
-    type: "file",
-    input: "./openapi.json",
-    path: "/api",
-    options: {
-      supportedLanguages: [
-        { value: "js", label: "JavaScript" },
-        { value: "python", label: "Python" },
-      ],
-      generateCodeSnippet: ({ selectedLang, selectedServer, operation, example }) => {
-        if (operation.operationId === "createUser") {
-          if (selectedLang === "js") {
-            return `
-import { Client } from "@mycompany/sdk";
-
-const client = new Client({ baseUrl: "${selectedServer}" });
-const user = await client.createUser(${JSON.stringify(example, null, 2)});
-            `.trim();
-          }
-          if (selectedLang === "python") {
-            return `
-from mycompany import Client
-
-client = Client(base_url="${selectedServer}")
-user = client.create_user(${JSON.stringify(example)})
-            `.trim();
-          }
-        }
-        // Return false to use default snippet generation
-        return false;
-      },
-    },
-  },
-};
-```
-
-The function receives:
-
-- `selectedLang`: Currently selected language from `supportedLanguages`
-- `selectedServer`: Currently selected server URL
-- `operation`: The OpenAPI operation object
-- `example`: The current request body example
-
-Return a string with the custom snippet, or `false` to fall back to default generation.
-
-## Extensions
-
-APIToGo supports OpenAPI extensions (properties starting with `x-`) to customize behavior at
-different levels of your API documentation.
-
-### Operations
-
-- `x-apitogo-playground-enabled`: Control playground visibility for an operation (default: `true`)
-- `x-explorer-enabled`: Alias for `x-apitogo-playground-enabled` for compatibility Example:
-
-```json
-{
-  "paths": {
-    "/users": {
-      "get": {
-        "summary": "Get users",
-        "x-apitogo-playground-enabled": false // Disable playground for this operation
-      }
-    }
-  }
-}
-```
-
-### Tags
-
-Extensions that can be applied to tag categories:
-
-- `x-apitogo-collapsed`: Control initial collapsed state of a tag category (default: `true`)
-- `x-apitogo-collapsible`: Control if a tag category can be collapsed (default: `true`)
-
-Example:
-
-```json
-{
-  "tags": [
-    {
-      "name": "Users",
-      "x-apitogo-collapsed": false
-    }
-  ]
-}
-```
-
-### Tag Groups
-
-Use `x-tagGroups` at the root of your OpenAPI document to group tags together in the navigation:
-
-```yaml
-x-tagGroups:
-  - name: Shipment
-    tags:
-      - Packages
-      - Parcels
-      - Letters
-```
-
-## Metadata
-
-Your API reference page metadata is sourced directly from your OpenAPI spec. The
-[`info`](https://spec.openapis.org/oas/v3.1.0#info-object) object is used set the corresponding tags
-in the page's `head`.
-
-| Metadata Property | OpenAPI Property | Comment                                                                                                                                         |
-| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| title             | `info.title`     | If `metadata.title` is set as a template string (ex. `%s - My Company`) it will be used                                                         |
-| description       | `info.summary`   | `info.summary` is preferred as it is shorter and plaintext-only, but APIToGo will fall back to the `info.description` if no summary is provided |
+---
+title: API reference
+sidebar_icon: book-open-check
+description: >-
+  The portal's API page: made from the gateway's OpenAPI file, pointed at the gateway, with Try it,
+  and the OpenAPI extensions that shape it.
+---
+
+The portal's **API Reference** page, at `/api`, is made from your gateway's OpenAPI file. There is
+nothing to set up: when the project has a `gateway` with `specs`, the page is there.
+
+```json title=apitogo.config.json
+{
+  "gateway": {
+    "origin": { "mode": "managed", "source": "server", "runtime": "nodejs" },
+    "specs": ["apitogo/apis/openapi.yaml"]
+  }
+}
+```
+
+The page uses the first file in `specs`. JSON and YAML both work.
+
+## What the page shows
+
+The page shows your API as people call it, through the gateway, not as it runs behind it:
+
+- **Servers** point at the gateway's address. Your origin's address never shows.
+- **Security** says what the gateway checks: the API key header (`X-API-Key` unless
+  `gateway.policies.access.apiKeyHeader` names another), and a bearer token when `gateway.auth` is
+  set.
+- Operations in `gateway.policies.operations.public` show no security, since they need no key.
+- Operations in `gateway.policies.operations.deny` are left out.
+
+Before the first deploy the gateway has no address yet, so `npx apitogo run` leaves the page out and
+says so. It appears once the gateway is deployed.
+
+## Try it
+
+Each operation has a **Try it** panel that sends a real request to the gateway. Under
+**Authentication** it offers:
+
+- **Your API key**: a key the visitor created on the API keys page, in this browser.
+- **Signed-in user**: the visitor's own sign-in token. It is offered only when the gateway checks
+  tokens (`gateway.auth`), since a gateway that checks keys would answer it with 401.
+
+Turn the panel off for one operation with `x-apitogo-playground-enabled: false` (below).
+
+## Who may read the OpenAPI file
+
+The platform also publishes the file for other docs tools. By default anyone may read it. To limit
+it to signed-in people:
+
+```json
+"gateway": { "export": { "access": "authenticated" } }
+```
+
+## OpenAPI extensions
+
+Fields starting with `x-` in your OpenAPI file change how the page looks.
+
+### Operations
+
+- `x-apitogo-playground-enabled`: show Try it for this operation (default `true`).
+  `x-explorer-enabled` is the same.
+
+```yaml
+paths:
+  /users:
+    get:
+      summary: Get users
+      x-apitogo-playground-enabled: false
+```
+
+### Tags
+
+- `x-apitogo-collapsed`: the tag's section starts collapsed (default `true`).
+- `x-apitogo-collapsible`: the tag's section can be collapsed (default `true`).
+
+```yaml
+tags:
+  - name: Users
+    x-apitogo-collapsed: false
+```
+
+### Tag groups
+
+Group tags in the sidebar with `x-tagGroups` at the root of the file:
+
+```yaml
+x-tagGroups:
+  - name: Shipment
+    tags: [Packages, Parcels, Letters]
+```
+
+## Page title and description
+
+The page's title and description come from the file's `info`: `info.title`, and `info.summary` (or
+`info.description` when there is no summary).