# @apidevtools/swagger-parser 中文文档

规范地址：https://npmcn.com/package/%40apidevtools/swagger-parser/

版本：13\.1\.0
npm 元数据更新时间：2026-09-20T19:30:54.682Z
中文译文更新时间：2026-11-06T09:59:39.450Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：56.3 kB，9 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：7 个
- peer 依赖：openapi-types \>=7
- 首次发布：2020-03-14T13:26:40.500Z
- 最新版本发布：2026-09-20T19:30:54.280Z
- 近 30 天下载量：24142483（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 2 个）

## 中文简介

Swagger 2.0 和 OpenAPI 3.0 解析器及节点和浏览器验证器

## 安装

```sh
npm install @apidevtools/swagger-parser
```

也可以使用：`pnpm add @apidevtools/swagger-parser`、`yarn add @apidevtools/swagger-parser`、`bun add @apidevtools/swagger-parser`

## README

# Swagger 2.0 和 OpenAPI 3.0 解析器/验证器

[![Build Status](https://github.com/APIDevTools/swagger-parser/workflows/CI-CD/badge.svg?branch=master)](https://github.com/APIDevTools/swagger-parser/actions) [![Coverage Status](https://coveralls.io/repos/github/APIDevTools/swagger-parser/badge.svg?branch=master)](https://coveralls.io/github/APIDevTools/swagger-parser) [![Tested on APIs.guru](https://api.apis.guru/badges/tested_on.svg)](https://apis.guru/browse-apis/)

[![npm](https://img.shields.io/npm/v/@apidevtools/swagger-parser.svg)](https://www.npmjs.com/package/@apidevtools/swagger-parser) [![Dependencies](https://david-dm.org/APIDevTools/swagger-parser.svg)](https://david-dm.org/APIDevTools/swagger-parser) [![License](https://img.shields.io/npm/l/@apidevtools/swagger-parser.svg)](https://npmcn.com/package/%40apidevtools/swagger-parser/LICENSE) [![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](https://shop.protect.earth/)

[![OS and Browser Compatibility](https://apidevtools.com/img/badges/ci-badges-with-ie.svg)](https://github.com/APIDevTools/swagger-parser/actions)

## 特征

-   将 Swagger 切入到 **贾森** 或者说 **也门** 格式
-   相对于 [Swagger 2.0 计划](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json) 或者说 [OpenAPI 3.0 司马](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v3.0/schema.json)
-   [决定:](https://apidevtools.com/swagger-parser/docs/swagger-parser.html#resolveapi-options-callback) 全部 `$ref` 指针,包括外部文件和 URL
-   可以吗 [捆绑](https://apidevtools.com/swagger-parser/docs/swagger-parser.html#bundleapi-options-callback) 您的所有 Swagger 文件都输入到只有一个文件 _内部_ `$ref` 指针
-   可以吗 [调试](https://apidevtools.com/swagger-parser/docs/swagger-parser.html#dereferenceapi-options-callback) 全部 `$ref` 指针,给您一个普通的 JavaScript 对象,该对象很容易使用
-   **[已测试](https://github.com/APIDevTools/swagger-parser/actions)** 在节点.js和Mac、Windows和Linux上的所有现代网页浏览器中
-   测试过 **[超过1500个真实世界的API](https://apis.guru/browse-apis/)** 来自谷歌,微软,Facebook,Spotify等.
-   支助 [参考文献](https://apidevtools.com/swagger-parser/docs/#circular-refs),嵌入式参考文献,回溯参考文献,并相互参照
-   保持对象引用平等 - `$ref` 指向同一值的总是对同一对象的解析

## 相关项目

-   [斯瓦格语CLI](https://github.com/APIDevTools/swagger-cli)
-   [Swagger Express 中间软件](https://github.com/APIDevTools/swagger-express-middleware)

## 示例

```javascript
SwaggerParser.validate(myAPI, (err, api) => {
  if (err) {
    console.error(err);
  } else {
    console.log("API name: %s, Version: %s", api.info.title, api.info.version);
  }
});
```

或使用 `async`编号 :`await` 或者说 [答应](http://javascriptplayground.com/blog/2015/02/promises/) 换成语法. 下例与上同

```javascript
try {
  let api = await SwaggerParser.validate(myAPI);
  console.log("API name: %s, Version: %s", api.info.title, api.info.version);
} catch (err) {
  console.error(err);
}
```

详情请参见 [API 文档](https://apidevtools.com/swagger-parser/docs/)

## 安装

使用 [无](https://docs.npmjs.com/about-npm/)数字 :

```bash
npm install @apidevtools/swagger-parser
```

需要节点.js 22.19或以后.

## 使用量

当在 Node.js 应用中使用 Swagger Parser 时, 您可能想要使用 **常见JS** 语法 :

```javascript
const SwaggerParser = require("@apidevtools/swagger-parser");
```

当使用诸如 [宝贝](https://babeljs.io/) 或者说 [类型脚本](https://www.typescriptlang.org/),或诸如 [网络软件包](https://webpack.js.org/) 或者说 [滚动](https://rollupjs.org/),您可以使用 **ECMAScript 模块** 语法代替 :

```javascript
import * as SwaggerParser from "@apidevtools/swagger-parser";
```

## 浏览器支持

Swagger Parser支持每个主要网页浏览器的最新版本. 旧浏览器可能需要 [宝贝](https://babeljs.io/) 和(或) [多元填充器](https://babeljs.io/docs/en/next/babel-polyfill)。 。 。 .

要在浏览器中使用 Swagger Parser, 您需要使用捆绑工具, 如 [网络软件包](https://webpack.js.org/), (中文(简体) ), [滚动](https://rollupjs.org/), (中文(简体) ), [括号](https://parceljs.org/),或 [浏览器](http://browserify.org/)。有些捆绑者可能需要一些配置,例如设置 `browser: true` 内 [卷起插件溶解](https://github.com/rollup/rollup-plugin-node-resolve)。 。 。 .

## API 文档

完备的 API 文档 [就在这里](https://apidevtools.com/swagger-parser/docs/)

## 警卫

默认情况下,该库试图使用 `$ref`,而不考虑文件扩展名或文件的位置。 这可以导致本地文件的包含(LFI),因此,潜在的敏感信息披露. 开发者在使用来自不信任来源的文档时必须谨慎. 见 [这里](https://npmcn.com/package/%40apidevtools/swagger-parser/SECURITY.md) 关于如何减轻LFI的详情和资料.

## 捐款

我欢迎任何贡献、增强和错误修正. [打开一个问题](https://github.com/APIDevTools/swagger-parser/issues) 关于 GitHub 和 [提交拉动请求](https://github.com/APIDevTools/swagger-parser/pulls)。 。 。 .

使用当前的Node.js LTS发行用于开发. TypeScript测试使用TypeScript 7编译器,而ESLint则通过TypeScript 6兼容API [微软推荐的包别名](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/#running-side-by-side-with-typescript-6-0)。 。 。 .

要在您的电脑上本地测试此工程 :

1.  **克隆这个还原**  
    `git clone https://github.com/APIDevTools/swagger-parser.git`
    
2.  **安装依赖关系**  
    `pnpm install`
    
3.  **运行测试**  
    `pnpm test`
    
4.  **检查密码覆盖**  
    `pnpm run coverage`
    

## 许可证

Swagger Parser 100% 自由且开源, 在 [麻省理工学院许可证](https://npmcn.com/package/%40apidevtools/swagger-parser/LICENSE)随意使用.

这个软件包是 [树件](http://treeware.earth/)如果你把它用于生产,那么我们要求你 [**给世界买一棵树**](https://shop.protect.earth/) 感谢我们的工作.

## 谢谢

感谢这些优秀的公司对开源开发商的支持 QQ

[![GitHub](https://apidevtools.com/img/badges/github.svg)](https://github.com/open-source) [![NPM](https://apidevtools.com/img/badges/npm.svg)](https://www.npmjs.com/) [![Coveralls](https://apidevtools.com/img/badges/coveralls.svg)](https://coveralls.io/)

## 常见问题

### @apidevtools/swagger-parser 是什么？

Swagger 2\.0 和 OpenAPI 3\.0 解析器及节点和浏览器验证器

### 如何安装 @apidevtools/swagger-parser？

在项目目录运行 npm install @apidevtools/swagger-parser，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：openapi-types（\>=7）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @apidevtools/swagger-parser 支持 TypeScript 吗？

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

### @apidevtools/swagger-parser 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @apidevtools/swagger-parser 需要什么版本的 Node\.js？

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

### @apidevtools/swagger-parser 可以商用吗？

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

### @apidevtools/swagger-parser 的下载量有多少？

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

### @apidevtools/swagger-parser 还在维护吗？

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