docs: add wormhole docs and update extension videos

Author: JOU-amjs

docs/api/07-wormhole.md

@@ -0,0 +1,178 @@
+---
+title: wormhole API
+---
+
+`@alova/wormhole` is a more modern openAPI generation solution for the alova library. It can generate API functions, complete API types, and complete API documents at the same time. Alova's development tools can eliminate the intermediate API documents for you, shortening the collaboration distance between the front-end and back-end like a wormhole. It is also the underlying implementation of the vscode extension.
+
+## Installation
+
+```bash
+# npm
+npm i @alova/wormhole -D
+# yarn
+yarn add @alova/wormhole -D
+# pnpm
+pnpm add @alova/wormhole -D
+```
+
+:::info extension installation tips
+
+If you are using vscode, it is strongly recommended that you use `@alova/wormhole` with alova's vscode extension. Please refer to [Editor Extension Integration](/tutorial/getting-started/extension-integration) to install vscode extension
+.
+
+If you are using other editors, you can also use the `@alova/wormhole` command to generate complete API information.
+
+:::
+
+## Commands
+
+### gen
+
+```bash
+alova gen [-f, --force] [-c --cwd <path>] [-w --workspace]
+```
+
+gen will look for the `alova.config.{cjs,js,mjs,ts}` configuration file and use it to automatically generate API related information.
+
+**Parameters:**
+
+- **-f, --force**: By default, the latest openAPI file will be checked for updates. If this parameter is specified, the check will be ignored and regeneration will be forced.
+
+- **-c, --cwd \<path\>**: Specify the working directory of the configuration file to be generated. The default is the current directory.
+
+- **-w, --workspace**: Specifies whether to generate in workspace mode. It will search for configuration files based on `workspaces` in `package.json` or subpackages defined in `pnpm-workspace.yaml`, and generate API-related information for all subpackages.
+
+### init
+
+```bash
+alova init [-t, --type <type>] [-c --cwd <path>]
+```
+
+Generate alova.config configuration file in the current directory. It will automatically generate configuration files with different suffixes according to the project type.
+
+**Parameters: **
+
+- **-t, --type**: Specifies the type of configuration file to be generated. The optional values ​​are: `auto/ts/typescript/module/commonjs`. The default is `auto`. It will automatically generate configuration files with different suffixes according to the project type.
+
+- **-c, --cwd \<path\>**: Specifies the working directory of the configuration file to be generated. The default is the current directory.
+
+## Node API
+
+### createConfig()
+
+Create a configuration file.
+
+- **Type**
+
+```ts
+type TemplateType = 'typescript' | 'module' | 'commonjs';
+interface ConfigCreationOptions {
+  projectPath?: string;
+  type?: TemplateType;
+}
+declare function createConfig(options?: ConfigCreationOptions): Promise<void>;
+```
+
+- **Parameter**
+
+1. `projectPath`: project path, default is `process.cwd()`.
+2. `type`: configuration file type, optional values ​​are `typescript`, `module`, `commonjs`.
+
+- **Example**
+
+```ts
+import { createConfig } from '@alova/wormhole';
+
+await createConfig();
+```
+
+### resolveWorkspaces()
+
+Search for all directories containing alova.config configuration files under the monorepo project. It will search for configuration files based on `workspaces` in `package.json` or subpackages defined in `pnpm-workspace.yaml`
+
+```ts
+declare function resolveWorkspaces(projectPath?: string): Promise<string[]>;
+```
+
+- **Parameter**
+
+1. `projectPath`: The project path to search, defaults to `process.cwd()`.
+
+- **Return value**
+
+An array of relative paths to directories containing alova.config configuration files.
+
+- **Example**
+
+```ts
+import { resolveWorkspaces } from '@alova/wormhole';
+const workspaces = await resolveWorkspaces();
+```
+
+### readConfig()
+
+Read the alova.config configuration file and return the parsed configuration object.
+
+```ts
+declare function readConfig(projectPath?: string): Promise<Config>;
+```
+
+- **Parameter**
+
+1. `projectPath`: The project path where the configuration file is located. The default value is `process.cwd()`.
+
+- **Return value**
+
+Configuration object.
+
+```ts
+import { generate } from '@alova/wormhole';
+const config = await readConfig();
+```
+
+### generate()
+
+Generate relevant API information based on the configuration object. Generally, it needs to be used with `readConfig()`.
+
+```ts
+type GenerateApiOptions = {
+  force?: boolean;
+  projectPath?: string;
+};
+declare function generate(config: Config, rules?: GenerateApiOptions): Promise<boolean[]>;
+```
+
+- **Parameters**
+
+1. `config`: configuration object, which is usually read by `readConfig` function.
+2. `rules`: generation rules, optional parameters are:
+   - `force`: whether to force regeneration, the default is `false`.
+   - `projectPath`: project path, the default is `process.cwd()`.
+
+- **Return value**
+
+An array that contains the result of `generator` items in configuration whether generation is successful.
+
+- **Example 1**
+
+Configuration files only exist in the root directory.
+
+```ts
+import { readConfig, generate } from '@alova/wormhole';
+
+const config = await readConfig();
+const results = await generate(config);
+```
+
+- **Example 2**
+
+Configuration files exist in multiple subpackages (monorepo).
+
+```ts
+import { readConfig, generate, resolveWorkspaces } from '@alova/wormhole';
+const workspaces = await resolveWorkspaces();
+for (const workspace of workspaces) {
+  const config = await readConfig(workspace);
+  await generate(config);
+}
+```

docs/tutorial/02-getting-started/09-extension-integration.md

@@ -8,16 +8,47 @@ Integrating Alova's editor extension can make it more powerful.
 2. Embed API documents in the code to experience the effect of checking and using APIs.
 3. Update APIs regularly and actively notify front-end developers, no longer relying on server-side developers to notify.
 
-<a className="button button--primary" href="vscode:extension/Alova.alova-vscode-extension">Install VS Code extension</a>
-
-> Automatically generate support for swagger-v2 and openapi-v3 specifications.
-
-The following is an extended demonstration video
+## Demo video
 
 import vscodeDemoVideo from '@site/static/video/vscode-demo-video-en.mp4';
 
 <video width="100%" controls controlsList="nodownload" src={vscodeDemoVideo} />
 
+## Install
+
+<a className="button button--primary" href="vscode:extension/Alova.alova-vscode-extension">Install VSCode extension (supports swagger-v2 and openapi-v3 specifications)</a>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+<TabItem value="1" label="npm">
+
+```bash
+npm install @alova/wormhole --save
+```
+
+</TabItem>
+<TabItem value="2" label="yarn">
+
+```bash
+yarn add @alova/wormhole
+```
+
+</TabItem>
+<TabItem value="3" label="pnpm">
+
+```bash
+pnpm add @alova/wormhole
+```
+
+</TabItem>
+</Tabs>
+
+Install `@alova/wormhole` and alova's vscode extension at the same time to enjoy the complete features. `@alova/wormhole` provides automatic generation features. The vscode extension can quickly call `@alova/wormhole` and provide shortcut keys for quickly finding interface documents in the editor.
+
+If you are using an editor such as WebStorm, you can use [@alova/wormhole's commands](/api/wormhole#commands) to automatically generate API call functions, complete TypeScript types of APIs, and API documentation information.
+
 ## Configuration
 
 When using the extension, you need to specify the input source and output directory from the openapi file, etc. You can create a configuration file in the project root directory, which supports the following formats:
@@ -35,27 +66,27 @@ The specific configuration parameters are as follows, taking commonjs as an exam
 ```js
 // alova.config.js
 module.exports = {
-  // API generation setting array, each item represents an automatically generated rule, including the generated input and output directories, standard file addresses, etc.
+  // API generation setting array, each item represents an automatically generated rule, including the generated input and output directories, standard file paths, etc.
   generator: [
     // Server 1
     {
-      // Input parameter 1: openapi json file url address
+      // Input parameter 1: openapi json file url url
       input: 'http://localhost:3000/openapi.json',
 
-      // Input parameter 2: local address with the current project as the relative directory
+      // Input parameter 2: local url with the current project as the relative directory
       // input: 'openapi/api.json'
 
-      // Input parameter 3: When there is no direct reference to the openapi file, it is a document address, and the document type must be specified with the platform parameter
+      // Input parameter 3: When there is no direct reference to the openapi file, it is a document url, and the document type must be specified with the platform parameter
       // input: 'http://192.168.5.123:8080'
 
       // (Optional) platform is a platform that supports openapi. Currently only swagger is supported. The default is empty
-      // When this parameter is specified, the input field only needs to specify the document address without specifying the openapi file
+      // When this parameter is specified, the input field only needs to specify the document url without specifying the openapi file
       platform: 'swagger',
 
-      // Output path of interface file and type file. Multiple generators cannot have the same address, otherwise the generated code will overwrite each other.
+      // Output path of interface file and type file. Multiple generators cannot have the same output path, otherwise the generated code will overwrite each other.
       output: 'src/api',
 
-      // (Optional) Specify the mediaType of the generated response data. Use this data type to generate the ts format of the response with a 200 status code. The default is application/json.
+      // (Optional) Specify the mediaType of the generated response data. Use this data type to generate the ts format of the response with a 2xx status code. The default is application/json.
       responseMediaType: 'application/json',
 
       // (Optional) Specify the bodyMediaType of the generated request body data. Use this data type to generate the ts format of the request body. The default is application/json.
@@ -77,8 +108,16 @@ module.exports = {
        */
       global: 'Apis',
 
+      /**
+       * The host object of global mounting, default is `globalThis`, it means `window` in browser and `global` in nodejs
+       */
+      globalHost: 'globalThis'
+
       /**
        * (Optional) Filter or convert the generated api interface function, return a new apiDescriptor to generate the api call function, if this function is not specified, the apiDescripor object is not converted
+       *
+       * The type of `apiDescriptor` is the same as the api item of openapi file.
+       * @see https://spec.openapis.org/oas/v3.1.0.html#operation-object
        */
       handleApi: apiDescriptor => {
         // Returning a falsy value means filtering this api
@@ -262,4 +301,6 @@ In this way, you can integrate the automatically generated code without changing
 
 1. In a ts project, if you find that vscode cannot correctly prompt, please set `"strictNullChecks": true` in `tsconfig.json`.
 
-2. Sometimes the api will prompt as `any` type, you can try to solve it as follows: Step 1, confirm whether this api is introduced in the entry file, and step 2, restart vscode
+2. Sometimes the api will prompt as `any` type, you can try to solve it as follows:
+   - Step 1, confirm whether this api is introduced in the entry file.
+   - Step 2, restart vscode

docusaurus.config.ts

@@ -211,14 +211,12 @@ const config: Config = {
     },
     announcementBar: {
       id: 'support_us',
-      content: `⭐️
-          If you also like alova,
-          <a
-            href="https://github.com/alovajs/alova"
-            target="_blank">
-            star it on GitHub!
-          </a>
-          ⭐️`,
+      content: `<span class="announcement">⭐️If you also like alova, 
+      <a
+        href="https://github.com/alovajs/alova"
+        target="_blank">
+        star it on GitHub!
+      </a>⭐️</span>`,
       backgroundColor: 'rgba(var(--ifm-color-primary-rgb), 0.05)'
       // textColor: '#fff'
     },