@lukoweb/apitogo 0.2.23 → 0.2.25

package/docs/configuration/api-reference.md

@@ -1,397 +1,397 @@
----
-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: 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 |