# @apidevtools/swagger-cli 中文文档

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

版本：4\.0\.4
npm 元数据更新时间：2026-01-24T16:02:51.849Z
中文译文更新时间：2026-11-06T10:00:04.332Z
软件包许可：MIT

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

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

弃用说明：This package has been abandoned\. Please switch to using the actively maintained @redocly/cli

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

- 包体积（解压后）：21.5 kB，9 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=10
- 运行依赖：4 个
- 首次发布：2020-03-14T14:33:56.187Z
- 最新版本发布：2020-07-19T14:21:27.373Z
- 近 30 天下载量：1338928（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 0 个）

## 中文简介

Swagger 2.0 和 OpenAPI 3.0 命令行工具

## 安装

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

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

## README

# 斯瓦格/ OpenAPI CPI

[![Cross-Platform Compatibility](https://apitools.dev/img/badges/os-badges.svg)](https://github.com/APIDevTools/swagger-cli/actions) [![Build Status](https://github.com/APIDevTools/swagger-cli/workflows/CI-CD/badge.svg?branch=master)](https://github.com/APIDevTools/swagger-cli/actions)

[![Dependencies](https://david-dm.org/APIDevTools/swagger-cli.svg)](https://david-dm.org/APIDevTools/swagger-cli) [![Coverage Status](https://coveralls.io/repos/github/APIDevTools/swagger-cli/badge.svg?branch=master)](https://coveralls.io/github/APIDevTools/swagger-cli?branch=master)

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

## 特征

-   验证 Swagger/ OpenAPI 文件中的 **JSON 或 YAML 软件** 格式
-   通过多文件 API 定义支持 `$ref` 指针
-   将多个 Swagger/ OpenAPI 文件装入一个合并文件

## 相关项目

-   [斯瓦格解析器](https://github.com/APIDevTools/swagger-parser)
-   [Swagger Express 中间软件](https://github.com/APIDevTools/swagger-express-middleware)

## 安装

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

```bash
npm install -g @apidevtools/swagger-cli
```

## 使用量

```
swagger-cli <command> [options] <file>

Commands:
    validate                Validates an API definition in Swagger 2.0 or OpenAPI 3.0 format

    bundle                  Bundles a multi-file API definition into a single file

Options:
    -h, --help              Show help for any command
    -v, --version           Output the CLI version number
    -d, --debug [filter]    Show debug output, optionally filtered (e.g. "*", "swagger:*", etc.)
```

### 验证 API

这个 `swagger-cli validate` 命令将对照 [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://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md),它会捕捉一些没有被计划覆盖的东西,例如重复参数,无效的MIME类型等.

如果 API 无效, 命令会以非零代码退出 .

```
swagger-cli validate [options] <file>

Options:
    --no-schema             Do NOT validate against the Swagger/OpenAPI JSON schema

    --no-spec               Do NOT validate against the Swagger/OpenAPI specification
```

#### Git 预承诺钩

有一个有用的 Python 工具叫做 [承诺前](https://pre-commit.com/) 用于执行一套广泛的承诺前检查。 这个 `swagger-cli validate` 命令可以通过将以下配置添加到 `repos` 现有条目 `.pre-commit-config.yaml` 文档.

```
-   repo: https://github.com/APIDevTools/swagger-cli
    rev: v2.2.1
    hooks:
    - id: swagger-validation
      args: ["validate", "<path to root swagger>"]
```

其用意是指出指向多条指向斯瓦克定义的单根分叉. 上面的钩子将执行 `swagger-cli validation` 任何匹配模式的文件 `.*swagger.*\.(json|yaml|yml)` 已修改。 这种验证的任何失败都会妨碍git承诺的处理.

### 合并多个文件

Swagger 和 OpenAPI 的 specs 允许您将您的 API 定义分成多个文件 [`$ref` 指针](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#reference-object) 以引用每个文件。 你可以用这个 `swagger-cli bundle` 命令将所有引用的文件合并为一个文件,这对分发或与其他工具的交互作用有用.

默认情况下 `swagger-cli bundle` 命令试图使输出文件大小尽可能小,只需嵌入每个引用文件 _一次_如果同一文件被多次引用,那么以后的任何引用都会被简单地修改以指向 _单人_ 文件的内含副本。 如果您想要生成一个捆绑的文件, 不需要 _任意_ `$ref` 指针,然后添加 `--dereference` 选项。 这将导致一个更大的文件大小,因为多次引用同一个文件将导致该文件被嵌入多次.

如果你没有具体说明 `--outfile` 选项,然后将捆绑的 API 写入 stdout ,这意味着您可以向其他命令管道它.

这种方法默认的结果被写为JSON. 可用 YAML 更改为 YAML `--type` 选项,通过 `yaml` 数值.

```
swagger-cli bundle [options] <file>

Options:
    -o, --outfile <file>        The output file

    -r, --dereference           Fully dereference all $ref pointers

    -f, --format <spaces>       Formats the output using the given number of spaces
                                (the default is 2 spaces)

    -t, --type <filetype>       Defines the output file type. The valid values are: json, yaml
                                (the default is JSON)

    -w, --wrap <column>         Set the line length for YAML strings
                                (the default is no wrapping)
```

## 捐款

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

#### 建筑物/试验

要在您的计算机上本地构建/测试项目:

1.  **克隆这个还原**  
    `git clone https://github.com/APIDevTools/swagger-cli.git`
    
2.  **安装依赖关系**  
    `npm install`
    
3.  **运行测试**  
    `npm test`
    

## 许可证

Swagger CLI 是100%的自由和开放源代码, 在 [麻省理工学院许可证](https://npmcn.com/package/%40apidevtools/swagger-cli/LICENSE)随意使用.

这个软件包是 [树件](http://treeware.earth/)如果你把它用于生产,那么我们要求你 [**给世界买一棵树**](https://plant.treeware.earth/APIDevTools/swagger-cli) 感谢我们的工作。 将会为当地家庭创造就业机会.

## 谢谢

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

[![Travis CI](https://jstools.dev/img/badges/travis-ci.svg)](https://travis-ci.com/) [![SauceLabs](https://jstools.dev/img/badges/sauce-labs.svg)](https://saucelabs.com/) [![Coveralls](https://jstools.dev/img/badges/coveralls.svg)](https://coveralls.io/)

## 常见问题

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

Swagger 2\.0 和 OpenAPI 3\.0 命令行工具注意：该包已被作者标记为弃用——This package has been abandoned\. Please switch to using the actively maintained @redocly/cli

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

在项目目录运行 npm install @apidevtools/swagger-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 swagger-cli，可以用 npx swagger-cli 直接运行。

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

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/apidevtools\_\_swagger-cli 是否存在。

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

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

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

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

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

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

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

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

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

最新版本 4\.0\.4 发布于 2020/07/19（6 年前）；至今共发布 6 个版本，其中过去 12 个月发布了 0 个；首次发布于 2020/03/14。作者已将其标记为弃用，新项目建议寻找替代方案。