# @api-platform/api-doc-parser 中文文档

规范地址：https://npmcn.com/package/%40api-platform/api-doc-parser/

版本：0\.16\.12
npm 元数据更新时间：2026-09-28T20:28:55.042Z
中文译文更新时间：2026-11-06T09:49:12.857Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：203 kB，127 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>= 20
- 运行依赖：4 个
- 首次发布：2017-10-05T21:37:17.310Z
- 最新版本发布：2026-09-28T20:28:54.714Z
- 近 30 天下载量：34498（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 3 个）

## 中文简介

在中间代表中转换一个API文档(Hydra,OpenAPI,GraphQL),可用于创建智能API客户端,脚手架代码或构建管理界面等各种任务.

## 安装

```sh
npm install @api-platform/api-doc-parser
```

也可以使用：`pnpm add @api-platform/api-doc-parser`、`yarn add @api-platform/api-doc-parser`、`bun add @api-platform/api-doc-parser`

## README

# ![API doc parser](https://github.com/user-attachments/assets/4d3bf8ba-8cbf-4673-9e6b-2cd30c9685d0)

# API Doc 解析器

**将 Hydra, Swagger/ OpenAPI, 和 GraphQL 光谱转换为您工具和应用程序的可操作数据 .**

[![CI](https://github.com/api-platform/api-doc-parser/actions/workflows/ci.yml/badge.svg)](https://github.com/api-platform/api-doc-parser/actions/workflows/ci.yml) [![GitHub License](https://img.shields.io/github/license/api-platform/api-doc-parser)](https://github.com/api-platform/api-doc-parser/blob/main/LICENSE) [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@api-platform/api-doc-parser)](https://bundlephobia.com/package/@api-platform/api-doc-parser) [![npm version](https://badge.fury.io/js/%40api-platform%2Fapi-doc-parser.svg)](https://badge.fury.io/js/%40api-platform%2Fapi-doc-parser) [![NPM Downloads](https://img.shields.io/npm/dw/%40api-platform%2Fapi-doc-parser)](https://img.shields.io/npm/dw/%40api-platform%2Fapi-doc-parser)

* * *

**`api-doc-parser` 是一个独立的 TypeScript 库,用于解析 [海德拉语Name](https://www.hydra-cg.com/), (中文(简体) ), [斯瓦格语Name](https://swagger.io/specification/v2/), (中文(简体) ), [打开API](https://github.com/OAI/OpenAPI-Specification#the-openapi-specification),以及 [图QL](https://graphql.org/) 将文件编入一个统一的中间代表制.**  
这种正态化的结构使得智能API客户端,代码生成器,管理员接口等等都能够实现.  
它与无缝结合 [API 平台](https://api-platform.com/) 框架.

## 关键特性

-   **统一产出** - 一个正常 `Api` 涵盖资源、领域、操作、参数和关系的对象
-   **类型脚本第一** - 对每个解析元素严格打字
-   **嵌入引用资源( R)** 自动解决
-   **框架整合** - 容易与API平台生态系统融合
-   **支持所有主要 API 格式** — Hydra, Swagger/ OpenAPI v2, OpenAPI v3, 和 GraphQL

## \* 安装

使用 [国家预防机制](https://www.npmjs.com/)数字 :

```
npm install @api-platform/api-doc-parser
```

使用 [N](https://pnpm.io/)数字 :

```
pnpm add @api-platform/api-doc-parser
```

与 [雅伦](https://yarnpkg.com/)数字 :

```
yarn add @api-platform/api-doc-parser
```

使用 [阿宝](https://bun.sh/)数字 :

```
bun add @api-platform/api-doc-parser
```

## 使用量

**海德拉语Name**

```javascript
import { parseHydraDocumentation } from "@api-platform/api-doc-parser";

const { api, response, status } = await parseHydraDocumentation(
  "https://demo.api-platform.com",
);
```

**OpenAPI v2( 原名 Swagger)**

```javascript
import { parseSwaggerDocumentation } from "@api-platform/api-doc-parser";

const { api, response, status } = await parseSwaggerDocumentation(
  "https://demo.api-platform.com/docs.json",
);
```

**打开API v3**

```javascript
import { parseOpenApi3Documentation } from "@api-platform/api-doc-parser";

const { api, response, status } = await parseOpenApi3Documentation(
  "https://demo.api-platform.com/docs.jsonopenapi?spec_version=3.0.0",
);
```

**图QL**

```javascript
import { parseGraphQl } from "@api-platform/api-doc-parser";

const { api, response } = await parseGraphQl(
  "https://demo.api-platform.com/graphql",
);
```

## ![TypeScript](https://api.iconify.design/vscode-icons:file-type-typescript-official.svg?color=%23888888&width=26&height=26) 类型定义

每个解析函数返回一个解析对象的保证,其中包含已归正的 API 结构、原始文档和 HTTP 状态代码 :

#### 打开API 3

```typescript
function parseOpenApi3Documentation(
  entrypointUrl: string,
  options?: RequestInitExtended,
): Promise<{
  api: Api;
  response: OpenAPIV3.Document;
  status: number;
}>;
```

#### 斯瓦格语Name

```typescript
function parseSwaggerDocumentation(entrypointUrl: string): Promise<{
  api: Api;
  response: OpenAPIV2.Document;
  status: number;
}>;
```

#### 海德拉语Name

```typescript
function parseHydraDocumentation(
  entrypointUrl: string,
  options?: RequestInitExtended,
): Promise<{
  api: Api;
  response: Response;
  status: number;
}>;
```

#### 图QL

```typescript
function parseGraphQl(
  entrypointUrl: string,
  options?: RequestInit,
): Promise<{
  api: Api;
  response: Response;
}>;
```

### 阿庇语Name

代表已解析的 API 的根,包含入站点 URL,可选标题,以及资源列表.

```typescript
interface Api {
  entrypoint: string;
  title?: string;
  resources?: Resource[];
}
```

### 资源

描述一个API资源(如实体或收藏),包括其领域、业务和元数据.

```typescript
interface Resource {
  name: string | null;
  url: string | null;
  id?: string | null;
  title?: string | null;
  description?: string | null;
  deprecated?: boolean | null;
  fields?: Field[] | null;
  readableFields?: Field[] | null;
  writableFields?: Field[] | null;
  parameters?: Parameter[] | null;
  getParameters?: () => Promise<Parameter[]> | null;
  operations?: Operation[] | null;
}
```

对于水利资源, `getParameters()` 懒散地装入参数并缓存 寿命计算结果 `Resource` 举个例子 运行文档 在 API 计划或授权后再次解析以刷新参数 上下文变化.

### 外地

资源财产,包括其类型、制约因素和元数据.

```typescript
interface Field {
  name: string | null;
  id?: string | null;
  range?: string | null;
  type?: FieldType | null;
  arrayType?: FieldType | null;
  enum?: { [key: string | number]: string | number } | null;
  reference?: string | Resource | null;
  embedded?: Resource | null;
  required?: boolean | null;
  nullable?: boolean | null;
  description?: string | null;
  maxCardinality?: number | null;
  deprecated?: boolean | null;
}
```

### 参数

代表一个收集/列表操作的查询参数,例如过滤器或页码变量.

```typescript
interface Parameter {
  variable: string;
  range: string | null;
  required: boolean;
  description: string;
  deprecated?: boolean;
}
```

### 字段类型

假设一个字段的可能类型,例如字符串、整数、日期等.

```typescript
type FieldType =
  | "string"
  | "integer"
  | "negativeInteger"
  | "nonNegativeInteger"
  | "positiveInteger"
  | "nonPositiveInteger"
  | "number"
  | "decimal"
  | "double"
  | "float"
  | "boolean"
  | "date"
  | "dateTime"
  | "duration"
  | "time"
  | "byte"
  | "binary"
  | "hexBinary"
  | "base64Binary"
  | "array"
  | "object"
  | "email"
  | "url"
  | "uuid"
  | "password"
  | string;
```

### 运行

代表可以在资源上执行的操作(如GET,POST,PUT,PATCH,DELETE等).

```typescript
interface Operation {
  name: string | null;
  type: "show" | "edit" | "delete" | "list" | "create" | null;
  method?: string | null;
  expects?: any | null;
  returns?: string | null;
  types?: string[] | null;
  deprecated?: boolean | null;
}
```

## QQ OpenAPI 支持

`api-doc-parser` 在解释 OpenAPI 文档时应用一套可预测的规则.  
如果不符合某项规则,则所涉资源将被默默跳出.

| 规则 | 细节 |
| --- | --- |
| **单个项目路径模式** | A 类 `GET` (已读)或 **`PUT`编号 :`PATCH`** (更新)终点 **必须** 匹配 :  
`/books/{id}` (单位:千美元) `^[^{}]+/{[^{}]+}/?$`) (中文(简体) ).  
`books` 可能是单数( o)`/book/{id}`) (中文(简体) ). |
| **Schema 发现** | **获取** ——第一次搜索 `responses → 200 → content → application/json`; 如果缺少, 倒回 `components` (组件名称必须是单数,例如:. `Book`) (中文(简体) ).  
**点/点** 仅 `requestBody → content → application/json` 考虑.  
如果两者都存在 & PUT/ PATCH 计划,则它们的领域是 **合并**。 。 。 . |
| **收藏路径** | 创建( A)`POST`)或清单(`GET`)终点 **必须** 复数 :  
`/books`。 。 。 . |
| **删除路径** | `DELETE` 必须在单项 GET 路径下生活(`/books/{id}`) (中文(简体) ). |
| **关系嵌入( E)** | 从财产名称及其JSON计划推断出资源之间的联系:  
二. 支助 **多元对象/阵列属性** (例如:. `reviews`, (中文(简体) ), `authors`成为 **内嵌** 当项目计划与现有资源相匹配时的资源(`Review`, (中文(简体) ), `Author`) (中文(简体) ).  
二. 支助 **类似ID的属性** (例如:. `review_id`, (中文(简体) ), `reviewId`, (中文(简体) ), `review_ids`, (中文(简体) ), `reviewIds`, (中文(简体) ), `authorId`)作为 **参考文献** 对资源.  
• 因此,如: **`reviews`** (对象/阵列)和 **`review_ids`** (标记/身份证阵列) **不变** `Review` 资源,一个标记 _内嵌_,另一个 _参考文献_。 。 。 . |
| **参数提取** | 参数改为 **仅限** 从列表路径( e)`/books`) (中文(简体) ). |

## QQ 支持其它格式( JSON: API, AsyncAPI...)

API Doc Parser旨在解析任何API文档格式并转换为同一种中间代表. 如果您开发了另一种格式的解析器, 请 [打开拉请求](https://github.com/api-platform/api-doc-parser/pulls) 把它纳入图书馆.

## 捐款

欢迎捐款! 协助:

1.  **读我们 [行为守则](https://github.com/api-platform/api-doc-parser?tab=coc-ov-file#contributor-code-of-conduct)。 。 。 .**
    
2.  **叉出寄存器并创建一个特性分支.**
    
3.  **确保你拥有 _最新消息_ 版本 [小时](https://pnpm.io/installation) 已安装.**
    
4.  **安装依赖关系**
    
    ```bash
    pnpm install
    ```
    
5.  **遵守代码样式和规则**
    
    ```bash
    pnpm lint:fix
    ```
    
    ```bash
    pnpm format
    ```
    
6.  **运行测试**
    
    ```bash
    pnpm test
    ```
    
7.  **确保类型正确**
    
    ```bash
    pnpm typecheck
    ```
    
8.  **提交一个拉动请求, 并清楚描述您的更改 .**
    

## • 贡献者

[![Contributors](https://contrib.rocks/image?repo=api-platform/api-doc-parser)](https://github.com/api-platform/api-doc-parser/graphs/contributors)

## QQ 星际历史

[![Star History Chart](https://api.star-history.com/svg?repos=api-platform/api-doc-parser&type=Date)](https://www.star-history.com/#api-platform/api-doc-parser&Date)

## • 信贷

创建于 [凯文·邓格拉斯](https://dunglas.fr/)发起人: [莱-蒂勒斯.coop](https://les-tilleuls.coop/)。 。 。 .

## 许可证

这个项目根据麻省理工学院许可证颁发——见 [自由主义](https://npmcn.com/package/%40api-platform/api-doc-parser/LICENSE) 详细文件.

## 常见问题

### @api-platform/api-doc-parser 是什么？

在中间代表中转换一个API文档\(Hydra,OpenAPI,GraphQL\),可用于创建智能API客户端,脚手架代码或构建管理界面等各种任务\.

### 如何安装 @api-platform/api-doc-parser？

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

### @api-platform/api-doc-parser 支持 TypeScript 吗？

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

### @api-platform/api-doc-parser 支持 ESM 还是 CommonJS？

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

### @api-platform/api-doc-parser 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @api-platform/api-doc-parser 可以商用吗？

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

### @api-platform/api-doc-parser 的下载量有多少？

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

### @api-platform/api-doc-parser 还在维护吗？

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