openapi-format

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

openapi-format

Follow this skill when a user asks to transform an OpenAPI document with the

openapi-format

CLI.

当用户要求使用

openapi-format

CLI转换OpenAPI文档时，请遵循本技能。

Core workflow

核心工作流

Identify the target outcome first.

Determine exactly what should change: order, filtering, casing, generation, overlay, conversion, rename, output format, split.
Determine input source (local file, remote URL, or overlay
```
extends
```
fallback).

Choose command shape.

Prefer a single command with explicit input/output unless the user asks for stdout.
Use
```
--configFile
```
for reusable workflows.
Use
```
.openapiformatrc
```
for project defaults.

Keep config minimal.

Start from defaults.
Add only keys required for requested behavior.
Avoid writing exhaustive config unless requested.

Apply correct precedence.

Load
```
.openapiformatrc
```
only when
```
--configFile
```
is not supplied.
Load and merge
```
--configFile
```
values.
Apply CLI options last.

Normalize

--no-sort

and

--no-bundle

into

sort=false

and

bundle=false

Respect processing order.

generate -> filter -> overlay -> sort -> casing -> convertTo -> rename -> write/split/stdout

Produce the output safely.

Use
```
--output
```
for file writes.
If
```
--split
```
is true, require
```
--output
```
and treat it as split target root.
Use
```
--json
```
or
```
--yaml
```
for stdout output formatting.

首先确定目标结果。

明确需要更改的内容：顺序、过滤、大小写、生成、覆盖、转换、重命名、输出格式、拆分。
确定输入源（本地文件、远程URL或覆盖层的
```
extends
```
回退源）。

选择命令形式。

优先使用带有明确输入/输出的单个命令，除非用户要求输出到stdout。
对于可复用工作流，使用
```
--configFile
```
。
对于项目默认配置，使用
```
.openapiformatrc
```
。

保持配置最简。

从默认配置开始。
仅添加实现所需行为必需的配置项。
除非用户要求，否则不要编写详尽的配置。

遵循正确的优先级。

仅当未提供
```
--configFile
```
时，才加载
```
.openapiformatrc
```
。
加载并合并
```
--configFile
```
中的配置值。
最后应用CLI选项。

将

--no-sort

和

--no-bundle

标准化为

sort=false

和

bundle=false

。

遵守处理顺序。

生成 -> 过滤 -> 覆盖 -> 排序 -> 大小写修改 -> 版本转换 -> 重命名 -> 写入/拆分/stdout

安全生成输出。

使用
```
--output
```
进行文件写入。
如果
```
--split
```
为true，则必须指定
```
--output
```
，并将其视为拆分目标的根目录。
对于stdout输出格式，使用
```
--json
```
或
```
--yaml
```
。

Decision rules

决策规则

Filter semantics

过滤语义

Treat

methods

tags

operationIds

operations

flags

flagValues

responseContent

, and

requestContent

as removal filters.

Treat

inverseMethods

inverseTags

inverseOperationIds

inverseFlags

inverseFlagValues

inverseResponseContent

, and

inverseRequestContent

as keep filters.

Use
```
unusedComponents
```
to remove unreferenced components recursively (iterative cleanup).
Use
```
stripFlags
```
to delete marker fields after filtering.

将

methods

、

tags

、

operationIds

、

operations

、

flags

、

flagValues

、

responseContent

和

requestContent

视为移除过滤器。

将

inverseMethods

、

inverseTags

、

inverseOperationIds

、

inverseFlags

、

inverseFlagValues

、

inverseResponseContent

和

inverseRequestContent

视为保留过滤器。

使用
```
unusedComponents
```
递归移除未被引用的组件（迭代清理）。
使用
```
stripFlags
```
在过滤后删除标记字段。

Overlay behavior

覆盖层行为

Accept
```
--overlayFile
```
with
```
actions
```
.
If input file is omitted and overlay has
```
extends
```
, use
```
extends
```
as effective input.
Resolve local
```
extends
```
relative to overlay file directory.

接受带有
```
actions
```
的
```
--overlayFile
```
。
如果省略输入文件且覆盖层包含
```
extends
```
，则将
```
extends
```
作为有效输入。
相对于覆盖层文件目录解析本地的
```
extends
```
。

Sorting and components

排序与组件

Default sorting comes from
```
defaultSort.json
```
.
```
sortPathsBy
```
controls path ordering (
```
original
```
,
```
path
```
,
```
tags
```
).
```
--sortComponentsFile
```
controls which component groups are alphabetized.

--sortComponentsProps

alphabetizes schema properties in

components.schemas.*.properties

默认排序规则来自
```
defaultSort.json
```
。
```
sortPathsBy
```
控制路径排序方式（
```
original
```
、
```
path
```
、
```
tags
```
）。
```
--sortComponentsFile
```
控制哪些组件组按字母顺序排列。

--sortComponentsProps

对

components.schemas.*.properties

中的 schema 属性按字母顺序排列。

Output constraints

输出约束

```
--split
```
requires
```
--output
```
.
```
--keepComments
```
only affects YAML comment preservation.
```
--lineWidth
```
controls YAML line wrapping (
```
-1
```
means unlimited).

```
--split
```
必须配合
```
--output
```
使用。
```
--keepComments
```
仅影响YAML注释的保留。
```
--lineWidth
```
控制YAML行换行（
```
-1
```
表示无限制）。

Use references

参考资料

Open only what is needed:

```
references/feature-matrix.md
```
for option behavior, defaults, and interactions.
```
references/config-patterns.md
```
for minimal config templates.
```
references/command-recipes.md
```
for runnable command patterns.
```
references/troubleshooting.md
```
for failure diagnosis and fixes.

仅打开必要的资料：

```
references/feature-matrix.md
```
：用于查看选项行为、默认值及交互逻辑。
```
references/config-patterns.md
```
：用于获取最简配置模板。
```
references/command-recipes.md
```
：用于获取可直接运行的命令示例。
```
references/troubleshooting.md
```
：用于故障诊断和修复。

Delivery checklist

交付检查清单

Return the exact command(s) to run.
Return minimal config file contents if config files are needed.
Explain expected transformation result in plain terms.
Call out side effects (component pruning, split output tree, version conversion changes).
Highlight any assumptions (input path, output path, format, bundle behavior).

返回要运行的精确命令。
如果需要配置文件，返回最简配置文件内容。
用通俗易懂的语言解释预期的转换结果。
指出副作用（组件修剪、拆分输出目录结构、版本转换变更）。
突出任何假设条件（输入路径、输出路径、格式、合并行为）。