# @apiture/openapi-down-convert 中文文档

规范地址：https://npmcn.com/package/%40apiture/openapi-down-convert/

版本：0\.14\.2
npm 元数据更新时间：2025-11-13T21:07:54.075Z
中文译文更新时间：2026-11-06T10:21:55.318Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：87.2 kB，22 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2023-02-21T19:39:04.692Z
- 最新版本发布：2025-11-13T21:07:53.882Z
- 近 30 天下载量：110849（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 1 个）

## 中文简介

将 OpenAPI 3.1 转换为 OpenAPI 3.0 的工具

## 安装

```sh
npm install @apiture/openapi-down-convert
```

也可以使用：`pnpm add @apiture/openapi-down-convert`、`yarn add @apiture/openapi-down-convert`、`bun add @apiture/openapi-down-convert`

## README

# OpenAPI 向下转换

`openapi-down-convert` 是将 API 定义文档从 OpenAPI 3.1改为OpenAPI 3.0.

-   [OpenAPI 规格( OAS) 3.1.0 释放](https://github.com/OAI/OpenAPI-Specification/releases/tag/3.1.0) 说明从美洲组织3.0到美洲组织3.1的变动.
-   见 [从 OpenAPI 3.0 移动到 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0) 因为往另一个方向走 这个工具帮助"Undo"一些这些转变.

**3⁄4 ̄ ̧漯B**:这不是一个完全有力的工具。 它只做最起码的必要工作 美洲组织 3.1 API文件,以支持工具,如 `openapi-generator` 并不支持美洲组织第3.1条。 它只支持美洲国家组织3.1的特点,即 Apiture APIs使用. 星洲网.

**3⁄4 ̄ ̧漯B**: 向下转换会导致忠诚的丧失。 一些 API 信息 丢失.

## 安装和概要

该工具由Node.js执行.

### 国家防范机制

```bash
npm i @apiture/openapi-down-convert
```

```typescript
import { Converter, ConverterOptions } from './converter';
const options : ConverterOptions = { verbose: false,
                                     deleteExampleWithId: true,
                                     allOfTransform: false };
  const converter = new Converter(oas31Document, options);
  try {
    const oas30Document = converter.convert();
    ...
    }
  } catch (ex) {
    // handle the exception
  }
```

由于转换器的用例是在建造管道和CLI的使用中, 此操作是同步的, 不使用 `async/await/Promises`。 。 。 .

### QQ 命令行

安装 :

```bash
npm i -g @apiture/openapi-down-convert
```

然后使用 :

```bash
openapi-down-convert --input openapi-3.1.yaml --output openapi-3.0.yaml
```

命令行选项 :

```text
Usage: openapi-down-convert [options]

Options:
  -i, --input <input-file>               A OpenAPI 3.1 file name. Defaults to "openapi.yaml"
  -o, --output <output-file>             The output file, defaults to stdout if omitted
  -a, --allOf                            If set, convert complex $ref in JSON schemas to allOf
  --authorizationUrl <authorizationUrl>  The authorizationUrl for openIdConnect -> oauth2 transformation
  --tokenUrl <tokenUrl>                  The tokenUrl for openIdConnect -> oauth2 transformation
  -d, --delete-examples-with-id          If set, delete any JSON Schema examples that have an `id` property
  --oidc-to-oath2 <scopes>               Convert openIdConnect security to oath2.
  --convertJsonComments                  If used, convert `$comment` in JSON schemas
                                         to `x-comment`. If omitted, delete
                                         all `$comment` in JSON schemas.
                                         (Use `--verbose` to log deletion
                                         to stdout)
  -s, --scopes <scopes>                  If set, this JSON/YAML file describes the OpenID scopes.
                                         This is an alias for --oidc-to-oath2
  -v, --verbose                          Verbose output
  -V, --version                          output the version number
  -h, --help                             display help for command
```

动词模式记录标准出错输出流的所有变化.

工具在成功时返回 0 状态代码或非 0 状态代码 如果它找到无法下调的构造,例如 使用 `contentMediaType: application/octet-stream` 带有 `format` 其他 `binary`或者如果一个计划 `contentEncoding: base64` 并拥有 `format` 还没有 `base64`。 。 。 .

该工具只支持基于本地文件的文档,而不是URL. 下载要转换的文件 :

```bash
openapi-down-convert --input <(curl -s https://my.host/path/openapi-3.1.yaml) \
                     --output openapi-3.0.yaml
```

## OpenAPI 规格转换

以下是该工具执行的转换列表 :

### qq openapi 声明

变动 `openapi: 3.1.x` 改为 `openapi: 3.0.3`

### ⤓ `openIdConnect` 安全定义

替换 `openIdConnect` 带有 `oauth2` 安保要求 它们足够接近,就代码生成而言(例如: `openapi-generator`(中文(简体) ) 关心 - 它只是意味着 `Authorization: header` 必须有有效的符号.

说明: 只有在 `--oidc-to-oauth2` 选项 (或作别名, `--scopes`提供. 使用其他选项指定 `authorizationUrl` 财务报告和审定财务报表 `tokenUrl` 联 合 国 `oauth2` 安全定义.

TODO: 获取 OpenIdConnect 连接信息并提取授权和 其符号 URL .

```yaml
    accessToken:
      type: openIdConnect
      description: ...
      openIdConnectUrl: 'https://auth.apiture.com/openidConnectDiscovery'
```

变成类似的东西:

```yaml
accessToken:
  type: oauth2
  description: "OpenIDConnect authorization code flow via https://auth.apiture.com/openidConnectDiscovery"
  flows:
    authorizationCode:
      authorizationUrl: <authorizationUrl option>
      tokenUrl: <tokenUrl option>
      scopes:
        scope1: Allow the application to access your personal profile data.
        scope2: Allow the application to send email on your behalf.
        scope3: >-
          TODO: describe the 'scope3' scope.
        scope4: >-
          TODO: describe the 'scope4' scope.
```

工具扫描所有 `security` 在所有操作中创建对象 使用范围列表。 范围说明应为: 应在 `scopes.yaml`文件为简单 `scopeName: scope description` 配对 :

```yaml
scope1: Allow the application to access your personal profile data.
scope2: Allow the application to send email on your behalf.
```

### ⤓ `$ref` 对象重写

对于所有包含 `$ref` 有兄弟姐妹的物体(`description`,其他 替换 `$ref`: 纯度为 `allOf` 。例如:

```yaml
myProperty:
  description: Blah blah
  $ref: '#/components/schemas/MyArray'
```

改为:

```yaml
mySchema:
  description: Blah blah
  allOf:
    - $ref: '#/components/schemas/MyArray'
```

这也适用于参数或参数中使用的图案 `requestBody` 对象 和反应.

**说明** 此变换默认被禁用, 因为它会中断 `openapi-generator` 5.4 在引用的策略是数组的情况下. 它为此类案件生成打字符类型, 如

```typescript
  myProperty: Array | null;
model/Model.ts:26:23 - error TS2314: Generic type 'Array<T>' requires 1 type argument(s).
```

应该是

```typescript
  incompleteAccounts: Array<string> | null;
```

为了启用,使用 `allOfTransform: true` 选项 `Converter` 构造器 或 `--allOf` 命令行参数。 残疾时 `$ref` 相反 简化为 a [JSON 参考](https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03)。 。 。 .

其他(非JSON Schema) `$ref` 对象可以有 `description` 财务报告和审定财务报表 `summary`。 。 。 . `$ref` 对于OAS 3.0中的非舍标对象,不能有 `description` 财务报告和审定财务报表 `summary`。 。 。 . `openapi-down-convert` 简单地删除 `description` 财务报告和审定财务报表 `summary` 生成有效的 [JSON 参考](https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03) 根据美洲组织3.0的要求。 (由此产生的 OpenAPI 将使用 `description` 输入 `$ref` 目标。 )

### ⤓ `info.license.identifier`

删除 `info.license.identifier`。 。 。 .

### ⤓ `webhooks`

删除 `webhooks` 对象,如果存在.

### JSON Schema 相关变化

OAS 3. 0 使用较早的 JSON Schema 版本 (单位:千美元)[JSON Schema 规格 Wright 第00号草案](https://datatracker.ietf.org/doc/html/draft-wright-json-schema-00)) (中文(简体) ). 工具转换 `examples` 在计程器到单 `example`。 。 。 .

作为一种特殊情况,如果 `example` 包含 `id`,这是 如果 `--delete-examples-with-id` CLI 选项已设定 . 这个地址 [2081年光谱问题](https://github.com/stoplightio/spectral/issues/2081)。 。 。 .

### ++ 转换 `const` 改为 `enum`

转换使用的 JSON Schema `const` 改为: `enum` 一个值。 举个例子

```yaml
components:
  schema:
     version:
        description: The API version.
        type: string
        const: '1.0.0'
```

变成

```yaml
components:
  schema:
     version:
        description: The API version.
        type: string
        enum:
          - '1.0.0'
```

### 将类型数组转换为无效

如果一个计程器有一个完全由两个值组成的类型数组,并且其中之一 是字符串 `'null'`,该类型转换为非核字符串项目, 财务报告和审定财务报表 `nullable: true` 增入诸法.

例如:

```yaml
    myResponse:
      title: My Response
      description: Response from an API operation
      type: [ object, 'null' ]
      allOf:
        ...
```

变成

```yaml
    myResponse:
      title: My Response
      description: Response from an API operation
      type: object
      nullable: true
      allOf:
        ...
```

财务报告和审定财务报表

```yaml
    myResponse:
      title: My Response
      description: Response from an API operation
      type: array
      items:
        type: [ 'string', 'null' ]
        ...
```

变成

```yaml
    myResponse:
      title: My Response
      description: Response from an API operation
      type: array
      items:
        type: string
        nullable: true
        ...
```

这种转换不会处理更复杂的 `type` 数组 情景,例如:

```yaml
   type: [ number, string, boolean, 'null']
```

为了支持这一点,需要使用 `oneOf`, (中文(简体) ), 但这并非小事 因为其他的图谋属性可能 有可能(`properties`, (中文(简体) ), `allOf` (例如)

(欢迎捐款。 )

### 删除 `unevaluatedProperties`

工具删除 `unevaluatedProperties` 值,稍后引入 jSON Schema的版本, 由于美洲组织3.0 JSON Schema草稿7不支持这一点 用于OAS 3.0.

```yaml
    myResponse:
      title: My Response
      description: Response from an API operation
      type: object
      unevaluatedProperties: false
      allOf:
        ...
```

变成

```yaml
    myResponse:
      title: My Response
      description: Response from an API operation
      type: object
      allOf:
        ...
```

工具删除任何 `$id` 或者说 `$schema` 可能出现的关键字 里面的图案对象.

### ++ 转换 `$comment` 改为 `x-comment`

JSON Schema介绍 `$comment` (原始内容存档于2020-12-12). in schemas in 2020. 由于OAS 3.0使用JSON Schema Draft 4和一些工具 将旗下 `$comment` 由于无效,本工具将删除这些注释.

该工具的更早版本已转换 `$comment` 改为 `x-comment` 然而,其他工具不允许 `$comment` 可能不支持 `x-comment` 也一样.

使用 `--convert-schema-comments` CLI 选项或设置 `convertSchemaComments` 改为 `true` 输入 `Converter` 构造器选项 转换 `$comment` 改为 `x-comment` 而不是删除 `$comment`。 。 。 .

譬如说,

```yaml
    Problems:
      title: Problems
      description: Problem Items
      type: array
      maxItems: 1000
      $comment: >-
        The value 1000 here must match `maxItems` in the ProblemList schema.
      items:
         $ref: '#/components/schemas/apiProblem'
```

变成

```yaml
    Problems:
      title: Problems
      description: Problem Items
      type: array
      maxItems: 1000
      x-comment: >-
        The value 1000 here must match `maxItems` in the ProblemList schema.
      items:
         $ref: '#/components/schemas/apiProblem'
```

### 转换 `contentEncoding: base64` 改为 `format: byte`

JSON Schema 第7稿及以后使用 `contentEncoding` 指定 \[非JSON字符串内容的编码\] (单位:千美元)[https://json-schema.org/understand-json-schema/ reference/non json data 互联网档案馆的存檔,存档日期2013-12-22](https://json-schema.org/understanding-json-schema/reference/non_json_data)) (中文(简体) ). 草案4支持 `format: byte` 页:1 `Base64` 编码字符串.

此工具转换 `type: string` 计划如下:

2个

| 美洲组织 3.1 计划a | 美洲组织 3.0 计划a |
| --- | --- |
| 
type: string
contentEncoding: base64


 | 

type: string
format: byte


 |
| 

type: string
contentMediaType: 'application/octet-stream'


 | 

type: string
format: binary


 |

## 不支持的向下转换

目前,该工具不支持下列情况. 欢迎捐款!

-   `openapi-down-convert` 不转换 `exclusiveMinimum` 财务报告和审定财务报表 `exclusiveMaximum`, (中文(简体) ), `unevaluatedProperties`, (中文(简体) ), `patternProperties`, (中文(简体) ), `propertyNames` jSON Schema 2020-12中的定义;JSON Schema Draft 7不支持这些内容 用于美洲组织3.0
-   该工具只支持自成一体的文档. 它没有跟随或决心 外部 `$ref` 文档嵌入源文档.
-   请求机构和答复机构 `content` 对象转换,例如 反转 `content: { 'application/octet-stream': {} }` 作为 说明 [从 OpenAPI 3.0 移动到 3.1.0](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0)
-   其他转换 `contentEncoding` 数值(`7bit`, (中文(简体) ), `8bit`, (中文(简体) ), `binary`, (中文(简体) ), `quoted-printable`, (中文(简体) ), `base16`, (中文(简体) ), `base32`(注: `contentEncoding: base64` 由 转换为 `format: byte` (如上所示。 )
-   转换 `contentMediaType: 'type/subtype` 改为 `media: { type: 'type/subtype'}` 非JSON数据.

## 常见问题

### @apiture/openapi-down-convert 是什么？

将 OpenAPI 3\.1 转换为 OpenAPI 3\.0 的工具

### 如何安装 @apiture/openapi-down-convert？

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

### @apiture/openapi-down-convert 支持 TypeScript 吗？

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

### @apiture/openapi-down-convert 支持 ESM 还是 CommonJS？

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

### @apiture/openapi-down-convert 可以商用吗？

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

### @apiture/openapi-down-convert 的下载量有多少？

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

### @apiture/openapi-down-convert 还在维护吗？

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