@mehdad67/apitogo 0.1.24

package/docs/configuration/api-reference.md

@@ -0,0 +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=apitogo.config.ts
+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=apitogo.config.ts
+const config = {
+  // ...
+  apis: {
+    type: "url",
+    input: "https://rickandmorty.zuplo.io/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=apitogo.config.ts
+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=apitogo.config.ts
+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=apitogo.config.ts
+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=apitogo.config.ts
+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=apitogo.config.ts
+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=apitogo.config.ts
+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=apitogo.config.ts
+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=apitogo.config.tsx
+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 |

package/docs/configuration/authentication-auth0.md

@@ -0,0 +1,174 @@
+---
+title: Auth0 Setup
+sidebar_label: Auth0
+description:
+  Learn how to set up Auth0 authentication for APIToGo, including application configuration and
+  integration steps for secure API documentation access.
+---
+
+Auth0 is a flexible authentication and authorization platform that integrates seamlessly with
+APIToGo. This guide walks you through setting up Auth0 authentication for your documentation site.
+
+## Prerequisites
+
+If you don't have an Auth0 account, you can sign up for a
+[free Auth0 account](https://auth0.com/signup) that provides 7,000 monthly active users.
+
+## Setup Steps
+
+<Stepper>
+
+1. **Create Auth0 Application**
+
+   [Create a new Auth0 application](https://auth0.com/docs/get-started/auth0-overview/create-applications)
+   in the Auth0 dashboard:
+   - Select type **Single Page Web Applications**
+   - Give your application a descriptive name
+
+2. **Configure Auth0 Application**
+
+   In your Auth0 application settings, configure the following:
+
+   **Application URLs:**
+   - **Allowed Callback URLs**:
+     - Production: `https://your-site.com/oauth/callback`
+     - Preview (wildcard): `https://*.your-domain.com/oauth/callback`
+     - Local Development: `http://localhost:3000/oauth/callback`
+   - **Allowed Logout URLs**: Same as callback URLs above
+
+   - **Allowed Web Origins**:
+     - Production: `https://your-site.com`
+     - Preview (wildcard): `https://*.your-domain.com`
+     - Local development: `http://localhost:3000`
+
+   **Refresh Token Rotation:**
+   - **Allow Refresh Token Rotation**: Enabled
+   - **Rotation Overlap Period**: 0 seconds (recommended)
+
+   Keep the default **Refresh Token Expiration** settings unless you have specific requirements.
+
+3. Create an Auth0 API:
+   - Navigate to the [APIs section](https://manage.auth0.com/#/apis) in the Auth0 dashboard
+   - Click **Create API**
+   - Set a name (e.g., "APIToGo API") and an identifier (e.g., `https://your-domain.com/api`)
+   - Choose **RS256** as the signing algorithm
+   - Save the API
+
+   :::warning
+
+   This step is important. If you skip creating an API, APIToGo will not be able to validate the
+   tokens issued by Auth0, leading to authentication failures.
+
+   :::
+
+4. **Configure APIToGo**
+
+   Add the Auth0 configuration to your [APIToGo configuration file](./overview.md):
+
+   ```typescript
+   // apitogo.config.ts
+   export default {
+     // ... other configuration
+     authentication: {
+       type: "auth0",
+       domain: "your-domain.us.auth0.com",
+       clientId: "<your-auth0-client-id>",
+       audience: "https://your-domain.com/api", // Your Auth0 API identifier
+     },
+     // ... other configuration
+   };
+   ```
+
+   Where:
+   - **domain**: Your Auth0 domain (found in your application's Basic Information)
+   - **clientId**: The Client ID from your Auth0 application settings
+   - **audience**: The identifier of the Auth0 API you created (e.g., `https://your-domain.com/api`)
+
+</Stepper>
+
+## Advanced Configuration
+
+### Custom Scopes
+
+If you need additional scopes for your API access, you can specify them in the configuration:
+
+```typescript
+authentication: {
+  type: "auth0",
+  domain: "your-domain.us.auth0.com",
+  clientId: "<your-auth0-client-id>",
+  scopes: ["openid", "profile", "email", "read:api", "write:api"],
+}
+```
+
+### Enabling Logout
+
+APIToGo supports logout functionality for Auth0 tenants. For tenants created **on or after November
+14, 2023**, logout is automatically enabled through the OIDC
+[RP-Initiated Logout](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)
+endpoint.
+
+To enable logout for your Auth0 application:
+
+1. Ensure your **Allowed Logout URLs** are configured in Auth0 (see
+   [Configure Auth0 Application](#setup-steps) above)
+2. The logout URL should match your callback URL pattern (e.g., `https://your-site.com/` for
+   production)
+
+For older tenants, you may need to enable **RP-Initiated Logout** in your tenant settings. See the
+[Auth0 logout documentation](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0)
+for details.
+
+### Customizing the Prompt Parameter
+
+By default, APIToGo sets `prompt="login"` in the Auth0 authorization request, which forces users to
+re-enter their credentials even if they have a valid session. You can customize this behavior using
+the `options.prompt` configuration:
+
+```typescript
+authentication: {
+  type: "auth0",
+  domain: "your-domain.us.auth0.com",
+  clientId: "<your-auth0-client-id>",
+  audience: "https://your-domain.com/api",
+  options: {
+    prompt: "", // Omit the prompt parameter to allow silent authentication
+  },
+}
+```
+
+Valid values for the `prompt` parameter include:
+
+- `"login"` - Force users to re-enter their credentials even if they have a valid session (default)
+- `"consent"` - Force users to consent to authorization even if they previously consented
+- `"select_account"` - Force users to select an account (useful for multi-account scenarios)
+- `"none"` - No prompt is shown; silent authentication only
+- `""` (empty string) - Omit the prompt parameter, allowing Auth0 to handle authentication based on
+  session state
+
+When the prompt parameter is omitted (empty string), Auth0 will:
+
+- Silently authenticate the user if they have a valid session
+- Redirect to the login page if no valid session exists
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Callback URL Mismatch**: Ensure your callback URLs in Auth0 exactly match your site's URL,
+   including the `/oauth/callback` path.
+
+2. **CORS Errors**: Add your site's domain to the Allowed Web Origins in Auth0.
+
+3. **Authentication Loop**: Check that your Auth0 domain includes the protocol (`https://`) but no
+   trailing slash.
+
+4. **Token Validation Errors**: Ensure the audience in your APIToGo configuration matches the
+   identifier of the Auth0 API you created.
+
+## Next Steps
+
+- Learn about [protecting routes](./authentication.md#protected-routes) in your documentation
+- Explore other [authentication providers](./authentication.md#authentication-providers) supported
+  by APIToGo
+- Configure [user permissions](./authentication.md#user-data) based on Auth0 roles