@lukoweb/apitogo 0.2.22 → 0.2.24

package/docs/guides/processors.mdx

@@ -1,234 +1,234 @@
----
-sidebar_icon: cpu
----
-
-# Schema Processors
-
-Schema processors are functions that transform your OpenAPI schemas before they are used in the
-documentation. They are defined in your `apitogo.build.ts` file and can be used to modify schemas in
-various ways.
-
-:::tip
-
-For information on how to configure processors in your project, see the
-[Build Configuration](../configuration/build-configuration) guide.
-
-:::
-
-## Built-in Processors
-
-APIToGo provides several built-in processors that you can use to transform your schemas:
-
-### `removeExtensions`
-
-Removes OpenAPI extensions (`x-` prefixed properties) from your schema:
-
-```ts
-import { removeExtensions } from "@lukoweb/apitogo/processors/removeExtensions";
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [
-    // Remove all x- prefixed properties
-    removeExtensions(),
-
-    // Remove specific extensions
-    removeExtensions({
-      keys: ["x-internal", "x-deprecated"],
-    }),
-
-    // Remove extensions based on a custom filter
-    removeExtensions({
-      shouldRemove: (key) => key.startsWith("x-internal"),
-    }),
-  ],
-};
-
-export default buildConfig;
-```
-
-### `removeParameters`
-
-Removes parameters from your schema:
-
-```ts
-import { removeParameters } from "@lukoweb/apitogo/processors/removeParameters";
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [
-    // Remove parameters by name
-    removeParameters({
-      names: ["apiKey", "secret"],
-    }),
-
-    // Remove parameters by location
-    removeParameters({
-      in: ["header", "query"],
-    }),
-
-    // Remove parameters based on a custom filter
-    removeParameters({
-      shouldRemove: ({ parameter }) => parameter["x-internal"],
-    }),
-  ],
-};
-
-export default buildConfig;
-```
-
-### `removePaths`
-
-Removes paths or operations from your schema:
-
-```ts
-import { removePaths } from "@lukoweb/apitogo/processors/removePaths";
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [
-    // Remove entire paths
-    removePaths({
-      paths: {
-        "/internal": true,
-        "/admin": ["get", "post"],
-      },
-    }),
-
-    // Remove paths based on a custom filter
-    removePaths({
-      shouldRemove: ({ path, method, operation }) => operation["x-internal"],
-    }),
-  ],
-};
-
-export default buildConfig;
-```
-
-:::info
-
-If you are missing a processor that you think should be built-in, please don't hesitate to
-[open an issue on GitHub](https://github.com/lukoweb/apitogo-doc-tool/issues/new).
-
-:::
-
-## Custom Processors
-
-You can also create your own processors. Here's a simple example that adds a description to all
-operations:
-
-```ts
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-async function addDescriptionProcessor({ schema }) {
-  if (!schema.paths) return schema;
-
-  // Add a description to all operations
-  Object.values(schema.paths).forEach((path) => {
-    Object.values(path).forEach((operation) => {
-      if (typeof operation === "object") {
-        operation.description = "This is a public API endpoint";
-      }
-    });
-  });
-
-  return schema;
-}
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [addDescriptionProcessor],
-};
-
-export default buildConfig;
-```
-
-### Adding Server URLs
-
-```ts
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-async function addServerUrl({ schema }) {
-  return {
-    ...schema,
-    servers: [{ url: "https://api.example.com" }],
-  };
-}
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [addServerUrl],
-};
-
-export default buildConfig;
-```
-
-## Using Query Parameters to Split Schemas
-
-You can use the same OpenAPI file multiple times with different processing by appending query
-parameters to the file input string. These parameters are passed to your processors via the `params`
-argument, allowing you to filter or transform the schema differently for each variant.
-
-This is useful when you have a single schema containing multiple API versions or groups that you
-want to split into separate pages.
-
-Plain strings work out of the box. Version paths and dropdown labels are auto-generated from the
-query parameter values. For more control, use the object form with explicit `path` and `label`.
-
-```ts title=config
-const config = {
-  apis: {
-    type: "file",
-    input: [
-      // Object form: explicit path and label
-      {
-        input: "openapi.json?prefix=/v2",
-        path: "latest",
-        label: "Latest (v2)",
-      },
-      // Object form: explicit path, label auto-generated from params
-      {
-        input: "openapi.json?prefix=/v1.1",
-        path: "v1.1",
-      },
-      // Plain string: both path and label auto-generated from params
-      "openapi.json?prefix=/v1",
-    ],
-    path: "/api",
-  },
-};
-```
-
-```ts title=apitogo.build.ts
-import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
-
-const buildConfig: ApitogoBuildConfig = {
-  processors: [
-    ({ schema, params }) => {
-      const prefix = params.prefix;
-      if (!prefix) return schema;
-
-      return {
-        ...schema,
-        paths: Object.fromEntries(
-          Object.entries(schema.paths ?? {}).filter(([path]) => path.startsWith(prefix)),
-        ),
-      };
-    },
-  ],
-};
-
-export default buildConfig;
-```
-
-Each version tab will show only the endpoints matching that prefix. The query parameters are
-arbitrary key-value pairs that you define and consume in your processors.
-
-When schema download is enabled, param variants serve the processed (filtered) schema rather than
-the original file.
-
-## Best Practices
-
-- **Handle missing properties**: Check for the existence of properties before accessing them
-- **Return the schema**: Always return the transformed schema, even if no changes were made
-- **Use async/await**: Processors can be async functions, which is useful for more complex
-  transformations
-- **Chain processors**: Processors are executed in order, so you can chain multiple transformations
+---
+sidebar_icon: cpu
+---
+
+# Schema Processors
+
+Schema processors are functions that transform your OpenAPI schemas before they are used in the
+documentation. They are defined in your `apitogo.build.ts` file and can be used to modify schemas in
+various ways.
+
+:::tip
+
+For information on how to configure processors in your project, see the
+[Build Configuration](../configuration/build-configuration) guide.
+
+:::
+
+## Built-in Processors
+
+APIToGo provides several built-in processors that you can use to transform your schemas:
+
+### `removeExtensions`
+
+Removes OpenAPI extensions (`x-` prefixed properties) from your schema:
+
+```ts
+import { removeExtensions } from "@lukoweb/apitogo/processors/removeExtensions";
+import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
+
+const buildConfig: ApitogoBuildConfig = {
+  processors: [
+    // Remove all x- prefixed properties
+    removeExtensions(),
+
+    // Remove specific extensions
+    removeExtensions({
+      keys: ["x-internal", "x-deprecated"],
+    }),
+
+    // Remove extensions based on a custom filter
+    removeExtensions({
+      shouldRemove: (key) => key.startsWith("x-internal"),
+    }),
+  ],
+};
+
+export default buildConfig;
+```
+
+### `removeParameters`
+
+Removes parameters from your schema:
+
+```ts
+import { removeParameters } from "@lukoweb/apitogo/processors/removeParameters";
+import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
+
+const buildConfig: ApitogoBuildConfig = {
+  processors: [
+    // Remove parameters by name
+    removeParameters({
+      names: ["apiKey", "secret"],
+    }),
+
+    // Remove parameters by location
+    removeParameters({
+      in: ["header", "query"],
+    }),
+
+    // Remove parameters based on a custom filter
+    removeParameters({
+      shouldRemove: ({ parameter }) => parameter["x-internal"],
+    }),
+  ],
+};
+
+export default buildConfig;
+```
+
+### `removePaths`
+
+Removes paths or operations from your schema:
+
+```ts
+import { removePaths } from "@lukoweb/apitogo/processors/removePaths";
+import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
+
+const buildConfig: ApitogoBuildConfig = {
+  processors: [
+    // Remove entire paths
+    removePaths({
+      paths: {
+        "/internal": true,
+        "/admin": ["get", "post"],
+      },
+    }),
+
+    // Remove paths based on a custom filter
+    removePaths({
+      shouldRemove: ({ path, method, operation }) => operation["x-internal"],
+    }),
+  ],
+};
+
+export default buildConfig;
+```
+
+:::info
+
+If you are missing a processor that you think should be built-in, please don't hesitate to
+[open an issue on GitHub](https://github.com/lukoweb/apitogo-doc-tool/issues/new).
+
+:::
+
+## Custom Processors
+
+You can also create your own processors. Here's a simple example that adds a description to all
+operations:
+
+```ts
+import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
+
+async function addDescriptionProcessor({ schema }) {
+  if (!schema.paths) return schema;
+
+  // Add a description to all operations
+  Object.values(schema.paths).forEach((path) => {
+    Object.values(path).forEach((operation) => {
+      if (typeof operation === "object") {
+        operation.description = "This is a public API endpoint";
+      }
+    });
+  });
+
+  return schema;
+}
+
+const buildConfig: ApitogoBuildConfig = {
+  processors: [addDescriptionProcessor],
+};
+
+export default buildConfig;
+```
+
+### Adding Server URLs
+
+```ts
+import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
+
+async function addServerUrl({ schema }) {
+  return {
+    ...schema,
+    servers: [{ url: "https://api.example.com" }],
+  };
+}
+
+const buildConfig: ApitogoBuildConfig = {
+  processors: [addServerUrl],
+};
+
+export default buildConfig;
+```
+
+## Using Query Parameters to Split Schemas
+
+You can use the same OpenAPI file multiple times with different processing by appending query
+parameters to the file input string. These parameters are passed to your processors via the `params`
+argument, allowing you to filter or transform the schema differently for each variant.
+
+This is useful when you have a single schema containing multiple API versions or groups that you
+want to split into separate pages.
+
+Plain strings work out of the box. Version paths and dropdown labels are auto-generated from the
+query parameter values. For more control, use the object form with explicit `path` and `label`.
+
+```ts title=config
+const config = {
+  apis: {
+    type: "file",
+    input: [
+      // Object form: explicit path and label
+      {
+        input: "openapi.json?prefix=/v2",
+        path: "latest",
+        label: "Latest (v2)",
+      },
+      // Object form: explicit path, label auto-generated from params
+      {
+        input: "openapi.json?prefix=/v1.1",
+        path: "v1.1",
+      },
+      // Plain string: both path and label auto-generated from params
+      "openapi.json?prefix=/v1",
+    ],
+    path: "/api",
+  },
+};
+```
+
+```ts title=apitogo.build.ts
+import type { ApitogoBuildConfig } from "@lukoweb/apitogo";
+
+const buildConfig: ApitogoBuildConfig = {
+  processors: [
+    ({ schema, params }) => {
+      const prefix = params.prefix;
+      if (!prefix) return schema;
+
+      return {
+        ...schema,
+        paths: Object.fromEntries(
+          Object.entries(schema.paths ?? {}).filter(([path]) => path.startsWith(prefix)),
+        ),
+      };
+    },
+  ],
+};
+
+export default buildConfig;
+```
+
+Each version tab will show only the endpoints matching that prefix. The query parameters are
+arbitrary key-value pairs that you define and consume in your processors.
+
+When schema download is enabled, param variants serve the processed (filtered) schema rather than
+the original file.
+
+## Best Practices
+
+- **Handle missing properties**: Check for the existence of properties before accessing them
+- **Return the schema**: Always return the transformed schema, even if no changes were made
+- **Use async/await**: Processors can be async functions, which is useful for more complex
+  transformations
+- **Chain processors**: Processors are executed in order, so you can chain multiple transformations

package/docs/guides/static-files.md

@@ -1,55 +1,55 @@
----
-title: Static Files
-sidebar_icon: folder-open
-description:
-  Learn how to serve and reference static files like images and PDFs in your APIToGo documentation
-  using the public directory.
----
-
-APIToGo makes it easy to serve static files like images, PDFs, or any other assets alongside your
-documentation. Any files placed in the `public` directory will be served at the root path `/` during
-dev, and copied to the root of the dist directory as-is.
-
-Note that you should always reference `public` assets using root absolute path - for example,
-`public/icon.png` should be referenced in source code as `/icon.png`.
-
-## Usage
-
-1. Create a `public` directory in your project root if it doesn't exist already
-2. Place any static files in this directory
-3. Reference these files in your documentation using the root path `/`
-
-## Example
-
-If you have the following structure:
-
-```
-your-project/
-├── public/
-│   ├── images/
-│   │   └── diagram.png
-│   └── documents/
-│       └── api-spec.pdf
-└── ...
-```
-
-You can reference these files using markdown like this:
-
-```md
-![API Architecture](/images/diagram.png)
-```
-
-If you want users to download a file like a PDF, you can use an anchor tag like this:
-
-```html
-<a href="/documents/api-spec.pdf" download="/documents/api-spec.pdf">Download API specification</a>
-```
-
-## Relative paths
-
-If you want to reference a file that is in the same directory as the current file, you can also use
-a relative path:
-
-```md title="page.mdx"
-![API Architecture](./image.png)
-```
+---
+title: Static Files
+sidebar_icon: folder-open
+description:
+  Learn how to serve and reference static files like images and PDFs in your APIToGo documentation
+  using the public directory.
+---
+
+APIToGo makes it easy to serve static files like images, PDFs, or any other assets alongside your
+documentation. Any files placed in the `public` directory will be served at the root path `/` during
+dev, and copied to the root of the dist directory as-is.
+
+Note that you should always reference `public` assets using root absolute path - for example,
+`public/icon.png` should be referenced in source code as `/icon.png`.
+
+## Usage
+
+1. Create a `public` directory in your project root if it doesn't exist already
+2. Place any static files in this directory
+3. Reference these files in your documentation using the root path `/`
+
+## Example
+
+If you have the following structure:
+
+```
+your-project/
+├── public/
+│   ├── images/
+│   │   └── diagram.png
+│   └── documents/
+│       └── api-spec.pdf
+└── ...
+```
+
+You can reference these files using markdown like this:
+
+```md
+![API Architecture](/images/diagram.png)
+```
+
+If you want users to download a file like a PDF, you can use an anchor tag like this:
+
+```html
+<a href="/documents/api-spec.pdf" download="/documents/api-spec.pdf">Download API specification</a>
+```
+
+## Relative paths
+
+If you want to reference a file that is in the same directory as the current file, you can also use
+a relative path:
+
+```md title="page.mdx"
+![API Architecture](./image.png)
+```