# @genapi/parser 中文文档

规范地址：https://npmcn.com/package/%40genapi/parser/

版本：4\.1\.4
npm 元数据更新时间：2026-07-29T09:33:15.597Z
中文译文更新时间：2026-11-16T02:47:11.652Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40genapi/parser
原文对照：https://npmcn.com/package/%40genapi/parser/?lang=original
项目主页：https://github.com/hairyf/genapi#readme
源码仓库：https://github.com/hairyf/genapi

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：91.6 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2025-03-28T02:07:18.610Z
- 最新版本发布：2026-07-29T09:33:15.295Z
- 近 30 天下载量：3546（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 6 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @genapi/parser
```

也可以使用：`pnpm add @genapi/parser`、`yarn add @genapi/parser`、`bun add @genapi/parser`

## README

# @ genapi/ parser (帮助)

[![npm version](https://img.shields.io/npm/v/@genapi/parser)](https://npmjs.com/package/@genapi/parser) [![npm downloads](https://img.shields.io/npm/dm/@genapi/parser)](https://npm.chart.dev/@genapi/parser)

将 OpenAPI/Swagger 文档分解为内部数据图表(路径,参数,schema等),用于管道编译和代码生成.

## 安装

```bash
pnpm add @genapi/parser
```

## API 密码

## 变形

### `transformBaseURL(source)`

当配置被设定时, 将 baseURL 从配置输入 spec .

**示例**

```ts
transformBaseURL(spec)
// configRead.config.meta.baseURL and configRead.graphs.variables may be set from spec.host/schemes
```

### `transformOperation(options)`

应用 `config.transform.operation` (全球)和 `config.patch.operations` (静态)一个行动.

返回的对象包含最终 `name`, (中文(简体) ), `parameters`,以及 `responseType`说明: `parameters` 总是通过相同的数组实例; 当被补丁所覆盖时, 数组在原地被变异( 清除并重新填充) 所以调用者使用 `const` 参考文献仍然有效.

**示例**

```ts
const result = transformOperation({ configRead, name: 'getUserUsingGET', parameters, responseType: 'User' })
// result.name, result.parameters, result.responseType (after transform + patch)
```

### `transformQueryParams(name)`

变形查询代码源参数:可选 URLSearchParams 片段和选项列表更新.

**示例**

```ts
const urlSuffix = transformQueryParams('query', { body: [], options: ['query'], url: '/api' })
// urlSuffix may be '?${querystr}', body/options mutated
```

### `transformUrlSyntax(url)`

以模板字面或字符串字面和可选的前缀 BaseURL 来包装 URL.

**示例**

```ts
transformUrlSyntax('/user/${paths.id}', { baseURL: true }) // '${baseURL}/user/${paths.id}' as template
transformUrlSyntax('/api') // "'/api'"
```

## 轨迹

### `traversePaths(paths, callback)`

步行 OpenAPI 路径并引用每个路径 + 方法的回调,其中包含合并参数和选项.

**示例**

```ts
traversePaths(spec.paths, (config) => {
  const { path, method, parameters } = config
  // handle each operation
})
```

### `createParser(pathHandler)`

创建一个统一的解析器条目,用于重用常流:解析 spec → 注入上下文 → 变换 Base URL/定义 → 穿行道. 预设只需要执行路径Handler,避免重复的parser()并转换Paths锅炉板.

**示例**

```ts
const parser = createParser((config, ctx) => {
  const meta = parseMethodMetadata(config)
  ctx.functions.push({ name: meta.name, parameters: meta.parameters, body: [] })
})
const configRead = parser(configRead)
```

### `fillParameters(options, parameters)`

将路径级别参数与操作级别参数合并;操作参数按名称覆盖.

**示例**

```ts
fillParameters(pathItem.get, pathParams) // [...pathParams, ...get.parameters] with dedup by name
```

### `isParameter(p: { $ref? })`

类型守护(type guard):检查该值是否为内置参数(有名和入),而非$ref.

**示例**

```ts
if (isParameter(item)) { const { name, in: loc } = item }
```

### `isRequiredParameter(fields)`

返回是否需要指定字段(而不是索引签名 / 任何) .

**示例**

```ts
isRequiredParameter([{ name: 'id', required: true, type: 'string' }]) // true
isRequiredParameter([{ name: 'tag', required: false }]) // false
```

### `literalFieldsToString(fields)`

代码源的单个选项:有赤色标识符,有\[键,值\]配对(或分布).

**示例**

```ts
'a'
yields
{
a
};
['a',
'b']
yields
{
a:
b
};
['...',
'c']
yields
{
...c
}
Converts an array of LiteralField into a single comma-separated code string for object literals.
```

**示例**

```ts
literalFieldsToString([['method', "'GET'"], 'body']) // "method:'GET', body"
```

### `parseHeaderCommits(source)`

将 OpenAPI 信息(标题、描述、 swagger、 版本)摘录为已生成文件头的评论行.

**示例**

```ts
const comments = parseHeaderCommits(swaggerSpec)
// ['@title My API', '@swagger 2.0', '@version 1.0']
```

### `parseMethodMetadata()`

从路径/方法构建方法元数据(名称,url模板,响应类型,注释)并应用变换/patch.

**示例**

```ts
const meta = parseMethodMetadata(pathMethod)
// meta.name, meta.url, meta.responseType, meta.description
```

### `parseMethodParameters(schemas?)`

将路径/方法参数分解为函数选项(body,查询,路径,头等)并提供了代码源的配置.

**示例**

```ts
const config = parseMethodParameters({ method: 'get', path: '/user/{id}', parameters }, schemas)
// config.parameters, config.options, config.interfaces
```

### `parseOpenapiSpecification(source)`

将输入光谱规范化为 Swagger 2 — 类似形状:通过 Swagger 2 或者通过 swagger2 Towagger3 转换 OpenAPI 3.x .

**示例**

```ts
const spec = parseOpenapiSpecification(openApi3Doc)
// spec has host, basePath, definitions for downstream parser
```

### `parseParameterFiled(parameter)`

将单个 OpenAPI 参数转换为语句字段(名称、类型、要求、描述).

**示例**

```ts
const field = parseParameterFiled({ name: 'id', in: 'path', type: 'string', required: true })
// { name: 'id', type: 'string', required: true }
```

### `parseSchemaType(propertie)`

将 OpenAPI 计划(或属性) 确定为 TypeScript 类型字符串; 处理 $ref, allOf, 对象, 阵列, 原始 .

**示例**

```ts
parseSchemaType({ type: 'string' }) // 'string'
parseSchemaType({ $ref: '#/definitions/User' }) // 'User'
parseSchemaType({ type: 'array', items: { type: 'number' } }) // 'number[]'
```

### `replaceMainext(output?, ext)`

在输出路径中的.ts和.js之间交换文件扩展名(例如用于双重TS/JS预设).

**示例**

```ts
replaceMainext('src/api/index.ts', 'js') // 'src/api/index.js'
```

### `signAnyInter(fields)`

将索引签名 \[关键:字符串\] 附加到字段数组中(对于打开的对象类型) .

**示例**

```ts
signAnyInter(headerFields) // headerFields now has [key: string]: any
```

### `spliceEnumDescription(name, enums)`

为一个enum查询参数构建 JSDoc @param 线条(允许的值和示例查询字符串).

**示例**

```ts
spliceEnumDescription('status', ['a', 'b']) // "@param status 'a,b' | 'status=a&status=b'"
```

### `spliceEnumType(enums)`

从 enum 字符串中构建一个 TypeScript 联盟阵列类型(例如“ a ” QQ “ b” for range) .

**示例**

```ts
spliceEnumType(['draft', 'published']) // "('draft' | 'published')[]"
```

### `toUndefField(inType, schemas)`

解析来自 schemas 或默认地图的参数位置( 如 “ path” - > “ paths ” ) 的选项密钥 .

**示例**

```ts
toUndefField('query') // 'query'
toUndefField('body', { body: 'data' }) // 'data'
```

### `transformBodyStringify(name)`

机构 JSON 字符串变换的选项:选项列表和参数列表.

当参数不是FormData/any时,将正文选项替换为JSON.stringify (.) literal.

**示例**

```ts
transformBodyStringify('body', { options: ['body', 'query'], parameters: [{ name: 'body', type: 'CreateDto' }] })
// options may become [['body', 'JSON.stringify(body || {})'], 'query']
```

### `transformDefinitions(definitions)`

将 OpenAPI 定义(chemas)转换为语句Interface 条目并被推入上下文界面;应用配置转换/patch.

**示例**

```ts
transformDefinitions(spec.definitions)
// inject().interfaces now includes User, Order, etc.
```

### `transformFetchBody(url, options, spaceResponseType)`

根据响应类型返回基于获取的客户端(json/text/none/void)的请求/响应正文片段.

**示例**

```ts
transformFetchBody('url', ['method: "GET"'], 'User') // ['const response = await fetch(url, {...})', 'return response.json() as Promise<User>']
```

### `transformHeaderOptions(name)`

标题转换的选项:选项列表和参数列表.

将内容- Type 标题( 应用程序/ json 或多部分/ 窗体- 数据) 输入选项中, 当存在时删除独立的“ 标题” 选项 .

**示例**

```ts
transformHeaderOptions('headers', { parameters: [...], options: ['headers', 'body'] })
// options get 'headers' replaced with literal { 'Content-Type': 'application/json', ...headers }
```

### `transformParameters(parameters, options)`

参数/响应类型变换的选项(语法,取名空间,通用,推论).

变换参数类型和目标语法的响应类型(TypeScript vs ECMAScript JSDoc);变异参数和描述.

**示例**

```ts
const { spaceResponseType } = transformParameters(parameters, { configRead, interfaces, description: [], responseType: 'User', syntax: 'typescript' })
```

### `useRefMap(ref)`

从 $ref 路径取出最后一段( 如 “ #/ 定义/ 用户 ” - > “ 用户 ” ).

**示例**

```ts
useRefMap('#/definitions/UserDto') // 'UserDto'
```

### `varFiled(name)`

逃避编码源的属性名:如果包含非识别字符,则用引号来包装.

**示例**

```ts
varFiled('userId') // 'userId'
varFiled('data-id') // "'data-id'"
```

### `varName(string_)`

将字符串或路径片段转换成有效的PascalCase标识符(译出,条形非平面).

**示例**

```ts
varName('get /user/info') // 'UserInfo'
varName(['get', 'user', 'id']) // 'UserId'
```

## 许可证

[麻省理工学院](https://github.com/hairyf/genapi/blob/main/LICENSE)

* * *

_自动更新 [自动](https://automd.unjs.io/)_

## 常见问题

### 如何安装 @genapi/parser？

在项目目录运行 npm install @genapi/parser，或使用 pnpm add / yarn add / bun add。

### @genapi/parser 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @genapi/parser 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @genapi/parser 可以商用吗？

@genapi/parser 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @genapi/parser 的下载量有多少？

根据 npm 官方下载统计，@genapi/parser 在 2026/10/16 – 2026/11/14 这 30 天内被下载 3,546 次，日均约 118 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @genapi/parser 还在维护吗？

最新版本 4\.1\.4 发布于 2026/07/29（3 个月前）；至今共发布 19 个版本，其中过去 12 个月发布了 6 个；首次发布于 2025/03/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

