Merge pull request #74 from alovajs/feature/[email protected]

docs: 新增开发工具插件文档

Author: JOU-amjs

docs/resource/04-devtool-plugins/01-rename.md

@@ -0,0 +1,122 @@
+---
+title: Renaming
+---
+
+## Introduction
+
+This plugin is used to rename URLs and parameters of API interfaces, supporting multiple naming styles and custom transformation rules. Key features include:
+
+- Renaming for URLs, request parameters, path parameters, request bodies, response data, and reference type names.
+- Built-in naming conversions: camelCase, pascalCase, kebabCase, and snakeCase.
+- Support for custom matching rules and transformation functions.
+- Support for multi-rule configurations.
+
+## Basic Usage
+
+```javascript title="alova.config.js"
+import { defineConfig } from '@alova/wormhole';
+import { rename } from '@alova/wormhole/plugin';
+
+export default defineConfig({
+  generator: [
+    {
+      // ...
+      plugin: [
+        // Convert underscores in URLs to camelCase
+        rename({ style: 'camelCase' })
+      ]
+    }
+  ]
+});
+```
+
+## Configuration Parameters
+
+```typescript
+interface Config {
+  /**
+   * Scope of application, defaults to 'url'.
+   * url: API path
+   * params: Query parameters
+   * pathParams: Path parameters
+   * data: Request body data
+   * response: Response data
+   * refName: Reference type name
+   */
+  scope?: 'url' | 'params' | 'pathParams' | 'data' | 'response' | 'refName';
+
+  /**
+   * Matching rule. If not specified, all will be converted.
+   * string: Contains this string
+   * RegExp: Matches this regex
+   * function: Custom matching function
+   */
+  match?: string | RegExp | ((key: string) => boolean);
+
+  /**
+   * Naming style.
+   * camelCase: camelCase (userName)
+   * kebabCase: kebab-case (user-name)
+   * snakeCase: snake_case (user_name)
+   * pascalCase: PascalCase (UserName)
+   */
+  style?: 'camelCase' | 'kebabCase' | 'snakeCase' | 'pascalCase';
+
+  /**
+   * Custom transformation function.
+   * Executed before style conversion.
+   */
+  transform?: (apiDescriptor: ApiDescriptor) => string;
+}
+
+function rename(config: Config | Config[]): ApiPlugin;
+```
+
+> **Note** 1. `refName` and `kebabCase` cannot be configured simultaneously because type names cannot be in kebab-case format. 2. `params`, `pathParams`, `data`, and `response` only rename the first-level names.
+
+## Multi-Rule Configuration
+
+```javascript
+// Configure multiple transformation rules simultaneously.
+// Before: /api/get_data/{item_id}
+// After: /api/getData/{itemId}
+rename([
+  {
+    scope: 'url',
+    style: 'camelCase',
+    match: /_/ // Only convert parts containing underscores
+  },
+  {
+    scope: 'pathParams',
+    style: 'camelCase'
+  }
+]);
+```
+
+### Custom Matching Rules
+
+```javascript
+// Only rename parameter names longer than 5 characters.
+rename({
+  scope: 'params',
+  match: key => key.length > 5,
+  style: 'camelCase'
+});
+```
+
+### Custom Transformation Function
+
+```javascript
+// Rename specific parameters.
+rename({
+  scope: 'data',
+  match: ['user_info', 'order_list'],
+  transform: api => {
+    const map = {
+      user_info: 'user',
+      order_list: 'orders'
+    };
+    return map[api.key] || api.key;
+  }
+});
+```

docs/resource/04-devtool-plugins/02-tag-modifier.md

@@ -0,0 +1,72 @@
+---
+title: Tag Modifier
+---
+
+## Introduction
+
+This plugin is used to modify the `tags` of APIs from OpenAPI files.
+
+## Basic Usage
+
+```javascript title="alova.config.js"
+import { defineConfig } from '@alova/wormhole';
+import { tagModifier } from '@alova/wormhole/plugin';
+
+export default defineConfig({
+  generator: [
+    {
+      // ...
+      plugin: [
+        // Each API will call the callback function to return a new tag. If you don't want to modify a tag, return the original tag directly.
+        tagModifier(tag => tag.toUpperCase()); // Example: Convert tag to uppercase
+      ]
+    }
+  ]
+});
+```
+
+## Configuration Parameters
+
+```typescript
+type ModifierHandler = (tag: string) => string;
+
+function tagModifier(handler: ModifierHandler): ApiPlugin;
+```
+
+- `handler`: A function that takes the current `tag` as a parameter and returns the modified `tag`. If you don't want to modify it, return the original `tag` directly.
+
+## Examples
+
+### Example 1: Add a Prefix
+
+```javascript
+// Add "api_" prefix to all tags
+tagModifier(tag => `api_${tag}`);
+```
+
+### Example 2: Filter Specific Tags
+
+```javascript
+// Only modify tags containing "user"
+tagModifier(tag => {
+  if (tag.includes('user')) {
+    return tag.replace('user', 'member');
+  }
+  return tag; // Keep other tags unchanged
+});
+```
+
+### Example 3: Convert to Camel Case
+
+```javascript
+// Convert tags to camel case
+tagModifier(tag => {
+  return tag
+    .split('_')
+    .map((part, index) => {
+      if (index === 0) return part;
+      return part.charAt(0).toUpperCase() + part.slice(1);
+    })
+    .join('');
+});
+```

docs/resource/04-devtool-plugins/03-payload-modifier.md

@@ -0,0 +1,202 @@
+---
+title: Payload Modifier
+---
+
+## Introduction
+
+This plugin is designed to flexibly modify request and response parameters of API interfaces. It supports adding, deleting, and modifying parameter types, as well as adjusting parameter hierarchies via the `flat` feature.
+
+Key features include:
+
+- Supports modifying parameters in the following scopes: `params`, `pathParams`, `data`, and `response`.
+- Allows precise control over modification scope using parameter name matching rules (`match`).
+- Enables dynamic modification of parameter types and required status via the `handler` function.
+
+## Basic Usage
+
+```javascript title="alova.config.js"
+import { defineConfig } from '@alova/wormhole';
+import { payloadModifier } from '@alova/wormhole/plugin';
+
+export default defineConfig({
+  generator: [
+    {
+      // ...
+      plugin: [
+        // Modify the `userId` field in request parameters
+        payloadModifier([
+          {
+            scope: 'params',
+            match: key => key === 'userId',
+            handler: schema => {
+              return {
+                'attr1?': 'string', // Mark as optional
+                attr2: 'number', // Mark as required
+                attr3: {
+                  // Nested data
+                  innerAttr: ['string', 'number', 'boolean']
+                }
+              };
+            }
+          }
+        ])
+      ]
+    }
+  ]
+});
+```
+
+## Configuration Parameters
+
+### Type Definitions
+
+```typescript
+/**
+ * Scope of parameter modification
+ */
+type ModifierScope = 'params' | 'pathParams' | 'data' | 'response';
+
+/**
+ * Primitive types
+ */
+type SchemaPrimitive =
+  | 'number'
+  | 'string'
+  | 'boolean'
+  | 'undefined'
+  | 'null'
+  | 'unknown'
+  | 'any'
+  | 'never';
+
+/**
+ * Array type
+ */
+type SchemaArray = {
+  type: 'array';
+  items: Schema;
+};
+
+/**
+ * Reference type (optional parameters are marked with `?` at the end of the key)
+ */
+type SchemaReference = {
+  [attr: string]: Schema;
+};
+
+/**
+ * Data Schema (supports union types)
+ */
+type Schema =
+  | SchemaPrimitive
+  | SchemaReference
+  | SchemaArray
+  | Array<SchemaPrimitive | SchemaReference | SchemaArray>
+  | { oneOf: Schema[] }
+  | { anyOf: Schema[] }
+  | { allOf: Schema[] };
+
+/**
+ * Configuration interface
+ */
+interface Config<T extends Schema> {
+  /**
+   * Scope of application
+   */
+  scope: ModifierScope;
+
+  /**
+   * Matching rule
+   * - string: Parameter name contains this string
+   * - RegExp: Parameter name matches this regex
+   * - function: Custom matching function
+   */
+  match?: string | RegExp | ((key: string) => boolean);
+
+  /**
+   * Parameter modification handler
+   * @param schema Current parameter's Schema
+   * @returns Returns various parameter types:
+   * - Schema: Modified type
+   * - { required: boolean, value: Schema }: Marks the parameter as required/optional
+   * - void | null | undefined: Removes the field
+   */
+  handler: (
+    schema: T
+  ) => Schema | { required: boolean; value: Schema } | void | null | undefined;
+}
+
+/**
+ * Plugin function
+ */
+function payloadModifier(configs: Config<Schema>[]): ApiPlugin;
+```
+
+### Example Configurations
+
+#### Modify Parameter Type
+
+```javascript
+// Change the `age` field in `params` to `number` type
+payloadModifier([
+  {
+    scope: 'params',
+    match: 'age',
+    handler: () => 'number'
+  }
+]);
+```
+
+#### Modify Nested Parameters
+
+```javascript
+// Modify nested parameters in `data`
+payloadModifier([
+  {
+    scope: 'data',
+    match: 'user',
+    handler: () => ({
+      name: 'string',
+      age: 'number',
+      address: {
+        city: 'string',
+        zipCode: 'number'
+      }
+    })
+  }
+]);
+```
+
+#### Remove a Parameter
+
+```javascript
+// Remove the `debugInfo` field from `response`
+payloadModifier([
+  {
+    scope: 'response',
+    match: 'debugInfo',
+    handler: () => undefined
+  }
+]);
+```
+
+#### Union Types
+
+```javascript
+// Change the `id` field in `pathParams` to `string | number` type
+payloadModifier([
+  {
+    scope: 'pathParams',
+    match: 'id',
+    handler: () => ['string', 'number']
+  }
+]);
+```
+
+## Advanced Usage
+
+### Dynamically Modify Required Status
+
+```javascript
+// Mark the `email` field in `data` as required
+```