fix-openapi-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fix OpenAPI Spec

修复OpenAPI规范

Use this skill when the task is to diagnose an OpenAPI specification that is preventing it from running as mock or test.

当任务是诊断阻碍OpenAPI规范作为模拟服务或测试运行的问题时，使用此技能。

Canonical Paths

标准路径

Use these exact paths and file names everywhere in this workflow.

Editable spec copy:
```
<spec-name>-updated.<ext>
```
Actions log:
```
fix-log-<spec-name>-<current-date>.md
```

在整个工作流中统一使用以下精确路径和文件名。

可编辑规范副本：
```
<spec-name>-updated.<ext>
```
操作日志：
```
fix-log-<spec-name>-<current-date>.md
```

Workflow State Machine

工作流状态机

Phase 1 -> Phase 2 -> Phase 3 -> Phase 4 validation -> STOP for user approval -> Phase 4 fixes only if explicitly approved

阶段1 -> 阶段2 -> 阶段3 -> 阶段4验证 -> 停止并等待用户批准 -> 仅在明确批准后执行阶段4修复

Docker Execution Rule

Docker执行规则

Assume Docker is available and the Docker engine is running.

Do not ask the user about Docker availability before attempting

scripts/run_loop_test.sh

scripts/run_loop_test.ps1

scripts/validate_spec.sh

, or

scripts/validate_spec.ps1

Run the relevant script first.
If the script output indicates a Docker-specific failure such as Docker not being installed, Docker not being on
```
PATH
```
, Docker Desktop not being available, or the Docker daemon / engine not running, stop and ask the user exactly:
```
Please confirm if docker engine is running
```
Do not claim validation or loop testing is unavailable until after a script run fails for a Docker-specific reason.
If it appears to be a permissions issue, try resolving it using your environment’s built-in privilege escalation mechanisms available to you.

假设Docker可用且Docker引擎正在运行。

在尝试运行

scripts/run_loop_test.sh

、

scripts/run_loop_test.ps1

、

scripts/validate_spec.sh

或

scripts/validate_spec.ps1

之前，无需询问用户Docker是否可用。

先运行相关脚本。
如果脚本输出显示Docker相关故障，例如未安装Docker、Docker不在
```
PATH
```
中、Docker Desktop不可用，或Docker守护进程/引擎未运行，请停止操作并准确询问用户：
```
请确认Docker引擎是否正在运行
```
只有在脚本因Docker相关原因运行失败后，才能声称验证或循环测试不可用。
如果出现权限问题，请尝试使用环境中可用的内置权限提升机制解决。

Working area

工作区域

Ignore any old test files or log files that existed before this conversation. You'll work with the output of the relevant commands as per the workflow state machine.

忽略本次对话前存在的任何旧测试文件或日志文件。你将根据工作流状态机的要求，使用相关命令的输出进行操作。

Phase 1: Setup

阶段1：设置

Create a copy of the input spec path for edits named
```
<spec-name>-updated.<ext>
```
in the same directory as the source spec.

Note: Always edit the
```
-updated
```
copy, not the original spec.

Create a single append-only actions log file named
```
fix-log-<spec-name>-<current-date>.md
```
in the spec directory, with the following initial content:

# Actions log for <spec-file>

Update docker using this command:

docker pull specmatic/specmatic:latest

在源规范所在目录中，创建一个供编辑使用的输入规范副本，命名为
```
<spec-name>-updated.<ext>
```
。

注意：始终编辑
```
-updated
```
副本，而非原始规范。

在规范目录中创建一个仅允许追加内容的操作日志文件，命名为
```
fix-log-<spec-name>-<current-date>.md
```
，初始内容如下：

# Actions log for <spec-file>

使用以下命令更新Docker镜像：

docker pull specmatic/specmatic:latest

Phase 2: Auto-fix obscure errors

阶段2：自动修复模糊错误

Run the loop test script against the editable copy.
Immediately after the loop test ends, append a structured entry to
```
fix-log-<spec-name>-<current-date>.md
```
with this format:

## <title>
**Timestamp**: <timestamp>
**Action**: Loop test run
**Result**: [pass|fail] - <brief description of the result>

If the loop test passes, go to step 5, the final check. All failed tests are considered "must-fix" errors.
If the loop test fails, attempt to fix one of the errors following the guidelines for addressing errors, and then go back to step 1.
If any must-fix errors remain to be addressed, go back to step 1 and repeat the process until all must-fix errors have been addressed.
Final check: once all the tests are passing, go back to step one and run the loop test again to make sure that there are no errors left.

Guidelines for addressing errors:

Classify every failure before moving on:
- ```
Spec Issue
```
  : the run points to a concrete schema, example, enum,
```
$ref
```
  ,
```
required
```
  , or constraint defect in the spec.
- ```
Specmatic Bug
```
  : the error is unclear (does not identify a concrete spec defect or provide enough information to point directly to where the issue is), or if it appears that Specmatic cannot handle a value / feature in the spec that is perfectly legimiate (e.g. valid regex syntax, valid OpenAPI syntax, etc)
- Treat any opaque error as a
```
Specmatic Bug
```
  . "Opaque" means the message does not identify a concrete spec defect or does not provide enough information to fix the spec confidently.
- If relaxing or removing a valid constraint is used to make the workflow pass, log it as a
```
Specmatic Bug
```
  .
- A status mismatch is not opaque merely because the final summary only shows
```
R0002
```
  . Before classifying it as
```
Specmatic Bug
```
  , inspect the raw temp test log around the full request/response transcript. Look both above and below the failed scenario summary. Only classify as opaque if no response body or adjacent transcript contains a concrete contract path or rule violation.
- If Specmatic-generated traffic fails against the same specification, classify it as
```
Specmatic Bug
```
  unless the failing constraint is itself invalid OpenAPI, invalid syntax, or demonstrably conflicts with another schema rule such as enum/example values.

If the issue is classified as a

Specmatic Bug

, log it immediately when first observed in

fix-log-<spec-name>-<current-date>.md

, using this format:

## <title>
**Timestamp**: <timestamp>
**Action**: Issue Classification
**Error**: <error message that prompted this bug classification>
**Classification**: Specmatic Bug
**Reason**: <why this is considered a Specmatic Bug instead of a concrete spec defect>
**Logs**: <log snippet showing the issue that prompted the fix>

If the issue is classified as a

Spec Issue

, log it immediately when first observed in

fix-log-<spec-name>-<current-date>.md

, using this format:

## <title>
**Timestamp**: <timestamp>
**Action**: Issue Classification
**Error**: <error message that prompted this bug classification>
**Classification**: Spec Issue
**Reason**: <why this is considered a Spec Issue instead of a Specmatic Bug>
**Logs**: <log snippet showing the issue that prompted the fix>

Do not wait for the bug to be resolved before logging it.
Form a hypothesis about the cause of the error, and whether there is an allowed fix which you have not yet tried that will resolve it. Even if the error seems unclear or opaque, form a hypothesis anyway, make your best guess, based on the error message, field names, and schema context.
If allowed fixes are available to be tried as per the "Allowed fixes" section,
- attempt the fixes in order of preference as outlined,
- Immediately after applying a fix, append a structured entry to
```
fix-log-<spec-name>-<current-date>.md
```
  with the format:
```
## Fix: <summary of the fix>
**Timestamp**: <timestamp>
**Action**: Fix applied
**Fix**: <description>
**Reason**: <why you think this fix should resolve the issue>
**Logs**: <log snippet showing the issue that prompted the fix>
```
- Then go back to Step 1 of this phase and run the loop test again to see if the fix resolved the issue.

However if there are no more allowed fixes left to try and the issue remains unresolved, consider the issue addressed and log a "Specmatic Bug" entry in the following format:

## Unfixable: <summary of the bug>
**Timestamp**: <timestamp>
**Action**: Dropping issue as unfixable
**Classification**: Specmatic Bug
**Reason**: <Why you concluded that this was unfixable>
**Logs**: <log snippet showing the issue that prompted this conclusion>

When logging a failed loop run, include the most specific inner contract error found in the response body. Do not log only the outer status mismatch if the response body contains a deeper rule violation.
For example, log:
```
REQUEST.QUERY.path.to.something <error>
```
or
```
RESPONSE.BODY.path.to.something <error>
```
or
instead of:
```
confirm-payment-source returned 400 instead of 200
```
.

对可编辑副本运行循环测试脚本。
循环测试结束后，立即将结构化条目追加到
```
fix-log-<spec-name>-<current-date>.md
```
中，格式如下：

## <title>
**Timestamp**: <timestamp>
**Action**: Loop test run
**Result**: [pass|fail] - <brief description of the result>

如果循环测试通过，进入步骤5（最终检查）。所有失败的测试都被视为“必须修复”的错误。
如果循环测试失败，尝试按照错误处理指南修复其中一个错误，然后返回步骤1。
如果仍有“必须修复”的错误未处理，返回步骤1并重复流程，直到所有“必须修复”的错误都得到解决。
最终检查：所有测试通过后，返回步骤1再次运行循环测试，确保没有遗留错误。

错误处理指南：

在继续操作前，对每个失败进行分类：
- ```
Spec Issue
```
  ：运行结果指向规范中具体的模式（schema）、示例、枚举（enum）、
```
$ref
```
  、
```
required
```
  或约束缺陷。
- ```
Specmatic Bug
```
  ：错误不明确（未指出具体的规范缺陷，或未提供足够信息直接定位问题），或者Specmatic似乎无法处理规范中完全合法的特性/值（例如有效的正则表达式语法、有效的OpenAPI语法等）。
- 将任何模糊错误视为
```
Specmatic Bug
```
  。“模糊”指错误消息未指出具体的规范缺陷，或未提供足够信息以确保修复规范。
- 如果通过放宽或移除有效约束使工作流通过，将其记录为
```
Specmatic Bug
```
  。
- 状态不匹配并不只是因为最终摘要仅显示
```
R0002
```
  就视为模糊。在将其归类为
```
Specmatic Bug
```
  之前，请检查原始临时测试日志中完整请求/响应记录的相关内容。查看失败场景摘要的上下部分。只有当响应体或相邻记录中没有具体的契约路径或规则违反信息时，才归类为模糊错误。
- 如果Specmatic生成的流量在同一规范下运行失败，除非失败的约束本身是无效的OpenAPI、无效语法，或明显与其他模式规则（如枚举/示例值）冲突，否则归类为
```
Specmatic Bug
```
  。

如果问题被归类为

Specmatic Bug

，首次发现时立即将其记录到

fix-log-<spec-name>-<current-date>.md

中，格式如下：

## <title>
**Timestamp**: <timestamp>
**Action**: Issue Classification
**Error**: <error message that prompted this bug classification>
**Classification**: Specmatic Bug
**Reason**: <why this is considered a Specmatic Bug instead of a concrete spec defect>
**Logs**: <log snippet showing the issue that prompted the fix>

如果问题被归类为

Spec Issue

，首次发现时立即将其记录到

fix-log-<spec-name>-<current-date>.md

中，格式如下：

## <title>
**Timestamp**: <timestamp>
**Action**: Issue Classification
**Error**: <error message that prompted this bug classification>
**Classification**: Spec Issue
**Reason**: <why this is considered a Spec Issue instead of a Specmatic Bug>
**Logs**: <log snippet showing the issue that prompted the fix>

无需等待bug解决即可记录。
针对错误原因形成假设，以及是否存在尚未尝试的允许修复方法可以解决问题。即使错误看起来不明确或模糊，也要基于错误消息、字段名称和模式上下文做出最佳猜测。
如果有“允许的修复”部分中列出的修复方法可以尝试：
- 按照优先顺序尝试修复，
- 应用修复后立即将结构化条目追加到
```
fix-log-<spec-name>-<current-date>.md
```
  中，格式如下：
```
## Fix: <summary of the fix>
**Timestamp**: <timestamp>
**Action**: Fix applied
**Fix**: <description>
**Reason**: <why you think this fix should resolve the issue>
**Logs**: <log snippet showing the issue that prompted the fix>
```
- 然后返回本阶段的步骤1，再次运行循环测试以查看修复是否解决了问题。

但是如果没有更多允许的修复方法可以尝试且问题仍未解决，则认为该问题已处理，并按照以下格式记录一条“Specmatic Bug”条目：

## Unfixable: <summary of the bug>
**Timestamp**: <timestamp>
**Action**: Dropping issue as unfixable
**Classification**: Specmatic Bug
**Reason**: <Why you concluded that this was unfixable>
**Logs**: <log snippet showing the issue that prompted this conclusion>

记录失败的循环运行时，包含响应体中找到的最具体的内部契约错误。如果响应体包含更深层的规则违反，不要只记录外部的状态不匹配。
例如，记录：
```
REQUEST.QUERY.path.to.something <error>
```
或
```
RESPONSE.BODY.path.to.something <error>
```
而非：
```
confirm-payment-source returned 400 instead of 200
```
。

Phase 3: Report on auto-fix phase

阶段3：自动修复阶段报告

Prepare a console report for the user. Do not mention mechanics such as test execution details, mock startup details, or pass/fail runtime chatter.

Read fix log at
```
fix-log-<spec-name>-<current-date>.md
```
in order to identify Specmatic bugs and applied fixes. Do not depend on memory.
If it contains
```
Classification**: Specmatic Bug
```
, the final response MUST include a
```
Specmatic bugs:
```
section.
If it contains
```
Fix applied
```
, the final response MUST include a
```
Fixes applied:
```
section.
Specmatic bugs section should be followed by the Fixes applied section if both exist, else just the one that exists should be printed.
If any Specmatic bugs exist, the final response MUST say to send:
- original spec
- updated spec
- fix log
Do not substitute validation/test summaries for these sections.

The format for the Specmatic bugs section is:

Specmatic bugs:
- <bug title>: <brief description of the bug>
- <bug title>: <brief description of the bug>

Please send the following files to the Specmatic team for analysis:
- <original spec file>
- <updated spec file>
- <fix log file>

The format for the list of fixes applied is:

Fixes applied:
- <item fixed>: <brief description of the fix>
- <item fixed>: <brief description of the fix>

为用户准备一份控制台报告。请勿提及测试执行细节、模拟服务启动细节或运行时的通过/失败闲聊内容。

读取
```
fix-log-<spec-name>-<current-date>.md
```
中的修复日志，以识别Specmatic bug和已应用的修复。不要依赖记忆。
如果日志中包含
```
Classification**: Specmatic Bug
```
，最终响应必须包含
```
Specmatic bugs:
```
部分。
如果日志中包含
```
Fix applied
```
，最终响应必须包含
```
Fixes applied:
```
部分。
如果两者都存在，Specmatic bugs部分应在Fixes applied部分之前；否则仅显示存在的部分。
如果存在任何Specmatic bugs，最终响应必须告知用户发送：
- 原始规范
- 更新后的规范
- 修复日志
不要用验证/测试摘要替代这些部分。

Specmatic bugs部分的格式如下：

Specmatic bugs:
- <bug title>: <brief description of the bug>
- <bug title>: <brief description of the bug>

请将以下文件发送给Specmatic团队进行分析：
- <original spec file>
- <updated spec file>
- <fix log file>

Fixes applied部分的格式如下：

Fixes applied:
- <item fixed>: <brief description of the fix>
- <item fixed>: <brief description of the fix>

Phase 4: Address load time errors and warnings

阶段4：处理加载时错误和警告

Note: Even if the user asks to fix the spec, they really want control over what gets fixed, and how the fix is done. So Phase 4 validation may be run automatically, but Phase 4 fixes must never be applied automatically.

Run the validate command on the
```
<spec-name>-updated.<ext>
```
spec.
If there are no errors or warnings, report to the user that the spec is now valid and can be used for testing and mocking with Specmatic, and end the process.
If there are errors or warnings, do NOT fix any errors or warnings. Do not infer approval from the original request, or from prior sessions. Only proceed if the next user message explicitly approves fixing the listed Phase 4 issues or requests specific fixes. Instead, list them out (not just the ids, include the descriptions if Specmatic provided it), and ask the user if they want to address spec defects on the
```
-updated
```
copy.
For each load-time error or warning that the users wants to address:

Classify and log the error following the same classification and logging contract as in Phase 2.

Apply allowed fixes to the
```
-updated
```
copy based on the error messages and classification, following the same guidelines for allowed fixes as in Phase 2.
Repeat this phase until all actionable load-time errors are addressed.
If you conclude that an issue cannot be fixed using allowed fixes, log it as a "Specmatic Bug" following the same contract as in Phase 2, consider it addressed.

注意：即使用户要求修复规范，他们实际上希望控制修复的内容和方式。因此阶段4的验证可以自动运行，但阶段4的修复绝不能自动应用。

对
```
<spec-name>-updated.<ext>
```
规范运行验证命令。
如果没有错误或警告，告知用户该规范现在有效，可以与Specmatic一起用于测试和模拟，然后结束流程。
如果存在错误或警告，不要修复任何错误或警告。不要从原始请求或之前的会话中推断用户已批准。只有当用户的下一条消息明确批准修复列出的阶段4问题或请求特定修复时，才能继续操作。相反，列出这些错误或警告（不仅是ID，如果Specmatic提供了描述也要包含），并询问用户是否要在
```
-updated
```
副本上解决规范缺陷。
对于用户想要处理的每个加载时错误或警告：

按照阶段2中的分类和记录规则对错误进行分类和记录。

根据错误消息和分类，对
```
-updated
```
副本应用允许的修复，遵循阶段2中的允许修复指南。
重复本阶段，直到所有可处理的加载时错误都得到解决。
如果得出结论无法使用允许的修复方法解决问题，按照阶段2中的规则将其记录为“Specmatic Bug”，并认为该问题已处理。

Disallowed fixes

禁止的修复

The following changes are not allowed:

Widening a JSON schema from

additionalProperties: false

additionalProperties: true

Dropping a property from a JSON schema completely. At most you may make properties optional or mandatory
Changing descriptions, titles, summaries, and other metadata (these are never parsed by Specmatic)
Avoid changing the request or response datatype
Remove a security scheme from an API

以下更改不被允许：

将JSON模式从

additionalProperties: false

放宽为

additionalProperties: true

从JSON模式中完全删除属性。最多只能将属性设为可选或必填
修改描述、标题、摘要和其他元数据（这些内容永远不会被Specmatic解析）
避免更改请求或响应的数据类型
从API中移除安全方案

Allowed fixes

允许的修复

Guidelines for fixing constraints and examples:

If you feel that an obscure must-fix error is related to a constraint (datatype is still correct but constraint such as regex, minLength, maximum, etc is broken), attempt the following fixes in order of preference:
- If the constraint syntax is invalid, fix the syntax and re-attempt the loop test.
- If the loop test fails, then based on the field name and schema context, make an educated guess, update the constraint, and re-attempt the loop test.
- Final option, remove the constraint and re-attempt the loop test.
When an enum does not match the schema constraint, remove the constraint.
When an example value does not match schema, update the example value to something meaningful based on the datatype and field name.
If you get an error saying expected X status but got 400, it means the mock didn't like the request. You will find details adjacent to that message saying why the 400 was returned by the mock.
For regexes, Specmatic uses the dk.brics.automaton.Regexp library, which supports a specific regex syntax found in
```
references/briks-automaton-regex-rules.md
```
.

修复约束和示例的指南：

如果您认为模糊的必须修复错误与约束有关（数据类型仍然正确，但约束如正则表达式、minLength、maximum等存在问题），请按照以下优先顺序尝试修复：
- 如果约束语法无效，修复语法并重新尝试循环测试。
- 如果循环测试失败，根据字段名称和模式上下文做出合理猜测，更新约束并重新尝试循环测试。
- 最后一种选择：移除约束并重新尝试循环测试。
当枚举与模式约束不匹配时，移除约束。
当示例值与模式不匹配时，根据数据类型和字段名称更新示例值为有意义的内容。
如果收到错误提示“预期状态X但得到400”，表示模拟服务不接受该请求。您会在该消息附近找到模拟服务返回400的原因详情。
对于正则表达式，Specmatic使用dk.brics.automaton.Regexp库，该库支持
```
references/briks-automaton-regex-rules.md
```
中特定的正则表达式语法。

When a scenario fails with HTTP status mismatch

当场景因HTTP状态不匹配失败时

If a loop test reports

R0002: HTTP status mismatch

, do not classify it as opaque until you inspect the request/response transcript for that same failed scenario.

Specmatic often prints the detailed contract failure inside the mock response body, before the final

Unsuccessful Scenarios

summary. Search upward from the failed scenario or from

Specification expected status ... but response contained status 400

for the nearest preceding:

```
Response at ...
```
```
X-Specmatic-Result: failure
```
```
Error from contract <spec-file>
```
```
>> REQUEST...
```
```
R1003
```
,
```
R000x
```
,
```
OAS00xx
```
, or any schema path

If the response body contains a concrete

>> REQUEST...

>> RESPONSE...

path, treat that as the primary failure, not the outer

R0002

status mismatch.

Example:

Outer error:

Specification expected status 200 but response contained status 400

Response body detail:

>> REQUEST.BODY.payment_source.card.network_token.cryptogram

Classification: Spec Issue if the path points to a concrete schema constraint that can be fixed.

如果循环测试报告

R0002: HTTP status mismatch

，在检查该失败场景的请求/响应记录之前，不要将其归类为模糊错误。

Specmatic通常会在模拟响应体中打印详细的契约失败信息，位于最终的

Unsuccessful Scenarios

摘要之前。从失败场景或

Specification expected status ... but response contained status 400

向上搜索最近的以下内容：

```
Response at ...
```
```
X-Specmatic-Result: failure
```
```
Error from contract <spec-file>
```
```
>> REQUEST...
```
```
R1003
```
、
```
R000x
```
、
```
OAS00xx
```
或任何模式路径

如果响应体包含具体的

>> REQUEST...

或

>> RESPONSE...

路径，则将其视为主要失败，而非外部的

R0002

状态不匹配。

示例：

外部错误：

Specification expected status 200 but response contained status 400

响应体详情：

>> REQUEST.BODY.payment_source.card.network_token.cryptogram

分类：如果路径指向可修复的具体模式约束，则为
```
Spec Issue
```
。

Logging Contract (Mandatory)

记录规则（强制性）

After every loop test run: append one loop-run entry to
```
fix-log-<spec-name>-<current-date>.md
```
.
After every applied fix: append one fix entry to
```
fix-log-<spec-name>-<current-date>.md
```
.
For every observed
```
Specmatic Bug
```
or
```
Spec Issue
```
: append one matching classification entry to
```
fix-log-<spec-name>-<current-date>.md
```
.

每次循环测试运行后：向
```
fix-log-<spec-name>-<current-date>.md
```
追加一条循环运行条目。
每次应用修复后：向
```
fix-log-<spec-name>-<current-date>.md
```
追加一条修复条目。
对于每个观察到的
```
Specmatic Bug
```
或
```
Spec Issue
```
：向
```
fix-log-<spec-name>-<current-date>.md
```
追加一条对应的分类条目。

Available scripts

可用脚本

Note:

Scripts for MacOS / Linux require bash
Scripts for Windows require powershell

Scripts for MacOS / Linux (requires bash)

scripts/run_loop_test.sh
- runs the loop test
scripts/validate_spec.sh
- validates a spec

Scripts for Windows (requires powershell)

scripts/run_loop_test.ps1
- runs the loop test
scripts/validate_spec.ps1
- validates a spec

When running these scripts, resolve the path from the fix-openapi-spec skill bundle directory.

注意：

MacOS / Linux脚本需要bash环境
Windows脚本需要powershell环境

MacOS / Linux脚本（需要bash）

scripts/run_loop_test.sh
- 运行循环测试
scripts/validate_spec.sh
- 验证规范

Windows脚本（需要powershell）

scripts/run_loop_test.ps1
- 运行循环测试
scripts/validate_spec.ps1
- 验证规范

运行这些脚本时，从fix-openapi-spec技能包目录解析路径。