docs: 重新翻译和修复 OpenAPI 文档格式

- 修正 OpenAPI introduction 页面的标题层级和格式
- 统一代码块语言标识，将 TypeScript 改为 typescript
- 修复图片标签格式，使用正确的 HTML 标签
- 统一警告和提示的格式样式
- 修正内部链接格式，移除多余的路径
- 重新翻译 CLI 插件文档，确保与英文原文对应
- 修正表格格式和代码示例
- 统一术语翻译，提高可读性

Author: zuohuadong

docs/openapi/cli-plugin.md

@@ -1,8 +1,8 @@
-### CLI 插件
+## CLI 插件
 
 [TypeScript](https://www.typescriptlang.org/docs/handbook/decorators.html) 的元数据反射系统存在若干限制，例如无法确定类包含哪些属性，或识别某个属性是可选的还是必需的。不过，其中部分限制可以在编译时得到解决。Nest 提供了一个插件来增强 TypeScript 的编译过程，从而减少所需的样板代码量。
 
-> info **注意** 此插件为 **可选功能** 。如果愿意，您可以手动声明所有装饰器，或仅在需要的地方声明特定装饰器。
+> **提示** 此插件为**可选功能**。如果愿意，您可以手动声明所有装饰器，或仅在需要的地方声明特定装饰器。
 
 #### 概述
 
@@ -41,7 +41,7 @@ export class CreateUserDto {
 
 对于中型项目虽不算大问题，但一旦类数量庞大时就会变得冗长且难以维护。
 
-通过[启用 Swagger 插件](/openapi/cli-plugin#使用-cli-插件) ，上述类定义可以简化为：
+通过[启用 Swagger 插件](#使用-cli-插件)，上述类定义可以简化为：
 
 ```typescript
 export class CreateUserDto {
@@ -52,15 +52,15 @@ export class CreateUserDto {
 }
 ```
 
-> info **注意** Swagger 插件会从 TypeScript 类型和 class-validator 装饰器推导出@ApiProperty()注解。这有助于为生成的 Swagger UI 文档清晰地描述您的 API。然而，运行时的验证仍将由 class-validator 装饰器处理。因此仍需继续使用如 `IsEmail()`、`IsNumber()` 等验证器。
+> **注意** Swagger 插件会从 TypeScript 类型和 class-validator 装饰器推导出 `@ApiProperty()` 注解。这有助于为生成的 Swagger UI 文档清晰地描述您的 API。然而，运行时的验证仍将由 class-validator 装饰器处理。因此仍需继续使用如 `IsEmail()`、`IsNumber()` 等验证器。
 
 因此，如果您打算依赖自动注解生成文档，同时仍希望进行运行时验证，那么 class-validator 装饰器仍然是必需的。
 
-> info **提示** 在 DTO 中使用[映射类型工具](../openapi/mapped-types) （如 `PartialType`）时，请从 `@nestjs/swagger` 而非 `@nestjs/mapped-types` 导入它们，以便插件能够识别模式。
+> **提示** 在 DTO 中使用[映射类型工具](../openapi/mapped-types)（如 `PartialType`）时，请从 `@nestjs/swagger` 而非 `@nestjs/mapped-types` 导入它们，以便插件能够识别模式。
 
 该插件基于**抽象语法树**动态添加适当的装饰器。因此您无需为分散在代码中的 `@ApiProperty` 装饰器而烦恼。
 
-> info **提示** 插件会自动生成所有缺失的 swagger 属性，但如需覆盖这些属性，只需通过 `@ApiProperty()` 显式设置即可。
+> **提示** 插件会自动生成所有缺失的 swagger 属性，但如需覆盖这些属性，只需通过 `@ApiProperty()` 显式设置即可。
 
 #### 注释自省功能
 
@@ -112,7 +112,7 @@ export class SomeController {
 
 对于控制器，您不仅可以提供摘要，还能添加描述（备注）、标签（例如 `@deprecated`）以及响应示例，如下所示：
 
-```ts
+```typescript
 /**
  * Create a new cat
  *
@@ -130,7 +130,7 @@ async create(): Promise<Cat> {}
 
 要启用该插件，请打开 `nest-cli.json` 文件（如果使用 [Nest CLI](/cli/overview)）并添加以下 `plugins` 配置：
 
-```javascript
+```json
 {
   "collection": "@nestjs/schematics",
   "sourceRoot": "src",
@@ -142,9 +142,9 @@ async create(): Promise<Cat> {}
 
 您可以使用 `options` 属性来自定义插件的行为。
 
-```javascript
+```json
 {
-  "collection": "@nestjs/schematics",
+  "collection": "@nestjs/schematics", 
   "sourceRoot": "src",
   "compilerOptions": {
     "plugins": [
@@ -178,14 +178,14 @@ export interface PluginOptions {
 
 | 选项                     | 默认                        | 描述                                                                                                 |
 | ------------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------- |
-| dtoFileNameSuffix        | \['.dto.ts', '.entity.ts'\] | DTO（数据传输对象）文件后缀                                                                          |
-| controllerFileNameSuffix | .controller.ts              | Controller 文件后缀                                                                                  |
-| classValidatorShim       | true                        | 如果设为 true，该模块将复用 class-validator 的验证装饰器（例如 @Max(10) 会在模式定义中添加 max: 10） |
-| dtoKeyOfComment          | 'description'               | 在 ApiProperty 上设置注释文本的属性键                                                                |
-| controllerKeyOfComment   | 'summary'                   | 设置 ApiOperation 注释文本的属性键                                                                   |
-| introspectComments       | false                       | 如果设为 true，插件将根据注释为属性生成描述和示例值                                                  |
-| skipAutoHttpCode         | false                       | 禁用控制器中自动添加 @HttpCode() 的功能                                                              |
-| esmCompatible            | false                       | 如果设为 true，可解决使用 ESM({ "type": "module" })时遇到的语法错误                                  |
+| `dtoFileNameSuffix`        | `['.dto.ts', '.entity.ts']` | DTO（数据传输对象）文件后缀                                                                          |
+| `controllerFileNameSuffix` | `['.controller.ts']`              | Controller 文件后缀                                                                                  |
+| `classValidatorShim`       | `true`                        | 如果设为 true，该模块将复用 class-validator 的验证装饰器（例如 @Max(10) 会在模式定义中添加 max: 10） |
+| `dtoKeyOfComment`          | `'description'`               | 在 ApiProperty 上设置注释文本的属性键                                                                |
+| `controllerKeyOfComment`   | `'summary'`                   | 设置 ApiOperation 注释文本的属性键                                                                   |
+| `introspectComments`       | `false`                       | 如果设为 true，插件将根据注释为属性生成描述和示例值                                                  |
+| `skipAutoHttpCode`         | `false`                       | 禁用控制器中自动添加 @HttpCode() 的功能                                                              |
+| `esmCompatible`            | `false`                       | 如果设为 true，可解决使用 ESM({ "type": "module" })时遇到的语法错误                                  |
 
 每当更新插件选项时，请确保删除 `/dist` 文件夹并重新构建应用程序。如果您不使用 CLI 而是使用自定义的 `webpack` 配置，可以将此插件与 `ts-loader` 结合使用：
 
@@ -197,25 +197,23 @@ getCustomTransformers: (program: any) => ({
 
 #### SWC 构建器
 
-对于标准设置（非 monorepo），要在 SWC 构建器中使用 CLI 插件，您需要按照[此处](/recipes/swc#类型检查)所述启用类型检查。
+对于标准设置（非 monorepo），要在 SWC 构建器中使用 CLI 插件，您需要按照[此处](../recipes/swc#类型检查)所述启用类型检查。
 
 ```bash
 $ nest start -b swc --type-check
 ```
 
-对于 monorepo 设置，请按照[此处](/recipes/swc#monorepo-和-cli-插件)的说明操作。
+对于 monorepo 设置，请按照[此处](../recipes/swc#monorepo-和-cli-插件)的说明操作。
 
 ```bash
 $ npx ts-node src/generate-metadata.ts
-```
 # OR npx ts-node apps/{YOUR_APP}/src/generate-metadata.ts
 ```
 
 现在，序列化的元数据文件必须通过 `SwaggerModule#loadPluginMetadata` 方法加载，如下所示：
 
 ```typescript
 import metadata from './metadata'; // <-- file auto-generated by the "PluginMetadataGenerator"
-```
 
 await SwaggerModule.loadPluginMetadata(metadata); // <-- here
 const document = SwaggerModule.createDocument(app, config);
@@ -293,7 +291,6 @@ $ npx jest --clearCache
 
 ```bash
 # Find jest cache directory (usually /tmp/jest_rs)
-```
 # by running the following command in your NestJS project root
 $ npx jest --showConfig | grep cache
 # ex result:

docs/openapi/introduction.md

@@ -1,6 +1,6 @@
-### 介绍
+## 介绍
 
-[OpenAPI](https://swagger.io/specification/) 规范是一种与语言无关的定义格式，用于描述 RESTful API。Nest 提供了一个专用[模块](https://github.com/nestjs/swagger) ，可通过装饰器生成此类规范。
+[OpenAPI](https://swagger.io/specification/) 规范是一种与语言无关的定义格式，用于描述 RESTful API。Nest 提供了一个专用[模块](https://github.com/nestjs/swagger)，可通过装饰器生成此类规范。
 
 #### 安装
 
@@ -10,11 +10,11 @@
 $ npm install --save @nestjs/swagger
 ```
 
-#### 启动引导
+#### 引导程序
 
 安装过程完成后，打开 `main.ts` 文件并使用 `SwaggerModule` 类初始化 Swagger：
 
-```typescript title="main"
+```typescript title="main.ts"
 import { NestFactory } from '@nestjs/core';
 import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
 import { AppModule } from './app.module';
@@ -36,30 +36,30 @@ async function bootstrap() {
 bootstrap();
 ```
 
-> info **提示** 工厂方法 `SwaggerModule.createDocument()` 专门用于在请求时生成 Swagger 文档。这种方法有助于节省初始化时间，生成的文档是一个符合 [OpenAPI 文档](https://swagger.io/specification/#openapi-document)规范的可序列化对象。除了通过 HTTP 提供文档外，您还可以将其保存为 JSON 或 YAML 文件以多种方式使用。
+> **提示** 工厂方法 `SwaggerModule.createDocument()` 专门用于在请求时生成 Swagger 文档。这种方法有助于节省初始化时间，生成的文档是一个符合 [OpenAPI 文档](https://swagger.io/specification/#openapi-document)规范的可序列化对象。除了通过 HTTP 提供文档外，您还可以将其保存为 JSON 或 YAML 文件以多种方式使用。
 
-`DocumentBuilder` 用于构建符合 OpenAPI 规范的基础文档结构。它提供了多种方法用于设置标题、描述、版本等属性。要创建完整文档（包含所有已定义的 HTTP 路由），我们使用 `SwaggerModule` 类的 `createDocument()` 方法。该方法接收两个参数：应用实例和 Swagger 配置对象。此外，我们还可以提供第三个参数，其类型应为 `SwaggerDocumentOptions`。更多细节请参阅[文档配置章节](/openapi/introduction#文档选项) 。
+`DocumentBuilder` 用于构建符合 OpenAPI 规范的基础文档结构。它提供了多种方法用于设置标题、描述、版本等属性。要创建完整文档（包含所有已定义的 HTTP 路由），我们使用 `SwaggerModule` 类的 `createDocument()` 方法。该方法接收两个参数：应用实例和 Swagger 配置对象。此外，我们还可以提供第三个参数，其类型应为 `SwaggerDocumentOptions`。更多细节请参阅[文档选项章节](#文档选项)。
 
 创建文档后，我们可以调用 `setup()` 方法。该方法接收：
 
-1.  挂载 Swagger UI 的路径
-2.  应用实例
-3.  上面实例化的文档对象
-4.  可选配置参数（了解更多[请点击此处](/openapi/introduction#设置选项) ）
+1. 挂载 Swagger UI 的路径
+2. 应用实例  
+3. 上面实例化的文档对象
+4. 可选配置参数（了解更多[请点击此处](#设置选项)）
 
 现在可以运行以下命令启动 HTTP 服务器：
 
 ```bash
 $ npm run start
 ```
 
-当应用程序运行时，在浏览器中访问 `http://localhost:3000/api`，您将看到 Swagger 用户界面。
+当应用程序运行时，在浏览器中访问 `http://localhost:3000/api`，您将看到 Swagger UI。
 
-![](/assets/swagger1.png)
+<figure><img src="/assets/swagger1.png" /></figure>
 
-如你所见，`SwaggerModule` 会自动映射所有端点。
+如你所见，`SwaggerModule` 会自动反映所有端点。
 
-> info **提示** 要生成并下载 Swagger JSON 文件，请访问 `http://localhost:3000/api-json` （假设你的 Swagger 文档位于 `http://localhost:3000/api`）。你也可以仅通过 `@nestjs/swagger` 中的 setup 方法将其暴露在你选择的路由上，如下所示：
+> **提示** 要生成并下载 Swagger JSON 文件，请访问 `http://localhost:3000/api-json`（假设你的 Swagger 文档位于 `http://localhost:3000/api`）。你也可以仅通过 `@nestjs/swagger` 中的 setup 方法将其暴露在你选择的路由上，如下所示：
 >
 > ```typescript
 > SwaggerModule.setup('swagger', app, documentFactory, {
@@ -68,9 +68,8 @@ $ npm run start
 > ```
 >
 > 这将在 `http://localhost:3000/swagger/json` 上暴露它
-```
 
-> warning **警告** 当使用 `fastify` 和 `helmet` 时，可能会出现 [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) 问题，要解决此冲突，请按如下方式配置 CSP：
+> **警告** 当使用 `fastify` 和 `helmet` 时，可能会出现 [CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) 问题，要解决此冲突，请按如下方式配置 CSP：
 >
 > ```typescript
 > app.register(helmet, {
@@ -89,13 +88,12 @@ $ npm run start
 >   contentSecurityPolicy: false,
 > });
 > ```
-```
 
 #### 文档选项
 
 创建文档时，可以提供一些额外选项来微调库的行为。这些选项应为 `SwaggerDocumentOptions` 类型，具体如下：
 
-```TypeScript
+```typescript
 export interface SwaggerDocumentOptions {
   /**
    * List of modules to include in the specification
@@ -150,7 +148,7 @@ export interface SwaggerDocumentOptions {
 
 例如，若需确保库生成类似 `createUser` 而非 `UsersController_createUser` 的操作名称，可进行如下设置：
 
-```TypeScript
+```typescript
 const options: SwaggerDocumentOptions =  {
   operationIdFactory: (
     controllerKey: string,
@@ -160,16 +158,16 @@ const options: SwaggerDocumentOptions =  {
 const documentFactory = () => SwaggerModule.createDocument(app, config, options);
 ```
 
-#### 配置选项
+#### 设置选项
 
-您可以通过将一个符合 `SwaggerCustomOptions` 接口的配置对象作为第四个参数传递给 `SwaggerModule#设置` 方法来配置 Swagger UI。
+您可以通过将一个符合 `SwaggerCustomOptions` 接口的配置对象作为第四个参数传递给 `SwaggerModule#setup` 方法来配置 Swagger UI。
 
-```TypeScript
+```typescript
 export interface SwaggerCustomOptions {
   /**
    * If `true`, Swagger resources paths will be prefixed by the global prefix set through `setGlobalPrefix()`.
    * Default: `false`.
-   * @see ../faq/global-prefix
+   * @see https://docs.nestjs.com/faq/global-prefix
    */
   useGlobalPrefix?: boolean;
 
@@ -287,7 +285,7 @@ export interface SwaggerCustomOptions {
 }
 ```
 
-> **提示** `ui` 和 `raw` 是独立选项。禁用 Swagger UI(`ui: false`)不会禁用 API 定义(JSON/YAML)。反之，禁用 API 定义(`raw: []`)也不会影响 Swagger UI 的使用。
+> **提示** `ui` 和 `raw` 是独立选项。禁用 Swagger UI (`ui: false`) 不会禁用 API 定义 (JSON/YAML)。反之，禁用 API 定义 (`raw: []`) 也不会影响 Swagger UI 的使用。
 >
 > 例如，以下配置将禁用 Swagger UI 但仍允许访问 API 定义：
 >
@@ -296,11 +294,10 @@ export interface SwaggerCustomOptions {
 >   ui: false, // Swagger UI is disabled
 >   raw: ['json'], // JSON API definition is still accessible (YAML is disabled)
 > };
-> SwaggerModule.setup('api', app, options);
+> SwaggerModule.setup('api', app, documentFactory, options);
 > ```
 >
-> 在这种情况下，[http://localhost:3000/api-json](http://localhost:3000/api-json) 仍可访问，但 [http://localhost:3000/api](http://localhost:3000/api)（Swagger UI）将不可用。
-```
+> 在这种情况下，`http://localhost:3000/api-json` 仍可访问，但 `http://localhost:3000/api`（Swagger UI）将不可用。
 
 #### 示例