specmatic-openapi-spec-extractor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

specmatic-openapi-spec-extractor

Extract and refine an OpenAPI specification from an existing API codebase.

Any prompt that implies deriving an OpenAPI or Swagger contract from an existing application or codebase should select this skill, not a generic extraction-only skill.

从现有API代码库中提取并优化OpenAPI规范。

任何暗示从现有应用或代码库推导OpenAPI或Swagger契约的请求，都应选择此技能，而非通用的仅提取类技能。

Required Behavior

要求的行为

If this skill is selected, do all of the following:

In the first user-facing progress update, explicitly say you are using
```
specmatic-openapi-spec-extractor
```
.
Treat extraction as phase 1, not the final outcome.
Use the framework-native extraction tool/path for the detected framework. Do not substitute a manual, hand-authored spec when the framework has a supported extraction path in this skill.
If the required extraction tool/integration is missing from the codebase, add the minimum non-behavioral framework-specific integration needed so the framework can generate/export the spec, then extract from that generated output.
"Use if available" is not acceptable for supported frameworks. For supported frameworks, the agent must make the extraction path available in the project unless the user explicitly forbids code changes.
After extraction succeeds, continue into the mandatory post-extraction workflow below. Do not stop after saving the first generated spec.
Always prepare the final runnable contract-test assets for the user once extraction and refinement are complete, even if the live Docker-dependent loop cannot run yet.
Prefer source annotations/config first, overlay second, and direct edits to the extracted spec never.
Do not change application implementation behavior to improve the spec. Allowed code changes are limited to extraction-related annotations, comments, and non-behavioral config required by the extraction tooling.
Do not change method signatures, control flow, returned values, persistence logic, auth behavior, or any other runtime semantics unless the user explicitly asks for implementation changes.
When running Specmatic validation, examples checks, stubs, or contract tests, use only the shell/Docker commands documented by this skill. Do not use Specmatic MCP tools or any alternate Specmatic execution path while this skill is active.
If a later phase is blocked, explicitly say which phase is blocked and why.
Do not silently behave like a generic OpenAPI extraction task. Follow this skill's workflow explicitly.

Default execution order:

announce skill -> identify framework -> open one framework guide -> integrate extraction path if missing -> extract spec -> save spec -> inspect gaps -> refine -> re-extract -> prepare Specmatic setup -> run Specmatic feedback loop -> prepare final runnable deliverables

Use this exact style in the first progress update:

Using specmatic-openapi-spec-extractor to extract and refine the OpenAPI spec. I’m first identifying the framework and extraction path, then I’ll continue with post-extraction refinement.

如果选择了此技能，请执行以下所有操作：

在首次面向用户的进度更新中，明确说明你正在使用
```
specmatic-openapi-spec-extractor
```
。
将提取视为第一阶段，而非最终结果。
针对检测到的框架，使用框架原生的提取工具/路径。若该框架在此技能中有支持的提取路径，则不要手动编写规范。
如果代码库中缺少所需的提取工具/集成，请添加最少的非行为型框架特定集成，使框架能够生成/导出规范，然后从生成的输出中提取。
对于支持的框架，“有则使用”是不可接受的。除非用户明确禁止代码更改，否则Agent必须在项目中启用提取路径。
提取成功后，继续执行以下强制性的提取后工作流。不要在保存首个生成的规范后就停止。
提取和优化完成后，始终为用户准备最终可运行的契约测试资产，即使依赖Docker的实时循环尚未能运行。
优先使用源代码注释/配置，其次是覆盖层，绝对不要直接编辑提取的规范。
不要更改应用的实现行为来优化规范。允许的代码更改仅限于提取工具所需的与提取相关的注释、说明和非行为型配置。
除非用户明确要求更改实现，否则不要修改方法签名、控制流、返回值、持久化逻辑、认证行为或任何其他运行时语义。
运行Specmatic验证、示例检查、存根或契约测试时，仅使用此技能文档中记录的Shell/Docker命令。在此技能激活期间，不要使用Specmatic MCP工具或任何其他替代的Specmatic执行路径。
如果后续阶段被阻塞，请明确说明哪个阶段被阻塞以及原因。
不要默认表现得像通用的OpenAPI提取任务。请严格遵循此技能的工作流。

默认执行顺序：

announce skill -> identify framework -> open one framework guide -> integrate extraction path if missing -> extract spec -> save spec -> inspect gaps -> refine -> re-extract -> prepare Specmatic setup -> run Specmatic feedback loop -> prepare final runnable deliverables

首次进度更新请使用以下确切格式：

Using specmatic-openapi-spec-extractor to extract and refine the OpenAPI spec. I’m first identifying the framework and extraction path, then I’ll continue with post-extraction refinement.

Selection Heuristics

选择准则

Select this skill by default when the user asks to extract or generate an OpenAPI or Swagger spec from an existing application, even if they do not mention Specmatic, skills, validation, refinement, or overlays.

This skill should win over a generic extraction-only skill when:

The request is about "this application", "this project", or "this codebase"
The request implies deriving a contract from existing code, routes, handlers, controllers, or an already-built API
The request uses adjacent terms like API spec, API schema, Swagger docs, API docs, contract, reverse-engineer, infer, or document endpoints
The user wants the spec to be accurate, complete, hardened, or refined
The task involves an existing API implementation rather than writing a spec from scratch
The framework can generate an initial spec and then benefit from contract-test feedback

当用户要求从现有应用中提取或生成OpenAPI或Swagger规范时，默认选择此技能，即使他们未提及Specmatic、技能、验证、优化或覆盖层。

在以下情况下，此技能应优先于通用的仅提取类技能：

请求涉及“此应用”、“此项目”或“此代码库”
请求暗示从现有代码、路由、处理器、控制器或已构建的API中推导契约
请求使用了相关术语，如API规范、API架构、Swagger文档、API文档、契约、逆向工程、推断或文档化端点
用户希望规范准确、完整、强化或经过优化
任务涉及现有API实现，而非从零开始编写规范
框架可以生成初始规范并从契约测试反馈中获益

Docker Execution Rule

Docker执行规则

Assume Docker is available and the Docker engine is running.
Do not ask the user about Docker availability before attempting the documented Specmatic
```
docker pull
```
,
```
docker run
```
, validation, or test commands from this skill.
Attempt the Specmatic feedback loop first.
If command 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 the Specmatic feedback loop is blocked on Docker until after a Docker command 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引擎正在运行。
在尝试此技能文档中记录的Specmatic
```
docker pull
```
、
```
docker run
```
、验证或测试命令之前，不要询问用户Docker是否可用。
先尝试Specmatic反馈循环。
如果命令输出显示Docker特定的失败，如未安装Docker、Docker不在
```
PATH
```
中、Docker Desktop不可用或Docker守护进程/引擎未运行，请停止并准确询问用户：
```
Please confirm if docker engine is running
```
只有在Docker命令因Docker特定原因失败后，才能声称Specmatic反馈循环因Docker被阻塞。
如果出现权限问题，请尝试使用环境中内置的权限提升机制解决。

Mandatory Post-Extraction Workflow

提取后强制工作流

Once the first spec has been extracted, the agent must execute these phases in order:

If the framework-native extraction path is not already wired into the project, integrate it first using minimal non-behavioral code/config changes for that framework.
Extract the spec using the framework-native generator/export path, not by manually writing
```
openapi.yaml
```
.
Save the extracted spec to the repo.
Inspect the generated spec for obvious gaps such as wrong status codes, generic
```
*/*
```
content types, missing security, weak request/response schemas, and missing error responses.
Refine generation using source annotations/config first. Use overlay only when source-level fixes cannot express the required contract. Allowed refinements: annotations, decorators, doc comments, extraction-tool config, and overlay updates. Disallowed refinements without explicit user approval: implementation changes, behavioral changes, signature changes, data model changes made only to shape the contract, or business-logic edits.
Re-extract the spec after each meaningful refinement.
Attempt the Specmatic feedback loop using the documented
```
docker pull
```
,
```
docker run
```
, validation, and test commands from this skill.
If a Docker command fails for a Docker-specific reason, stop and ask the user exactly:
```
Please confirm if docker engine is running
```
Prepare the final deliverables from this skill, including
```
run_contract_tests.sh
```
and
```
CONTRACT_TESTS_README.md
```
, regardless of whether deterministic data setup is needed.
If Docker is unavailable, stop only after clearly reporting that extraction and refinement are done, the runnable script and README have been prepared, and the next blocked step is the live Specmatic loop.

Do not treat annotation-only cleanup as the full post-extraction workflow. Do not end the task after exporting

openapi.yaml

unless the user explicitly asks for extraction only. Do not claim the spec was "extracted" if the file was primarily authored by hand outside the framework generator/export path.

首次提取规范后，Agent必须按顺序执行以下阶段：

如果框架原生提取路径尚未接入项目，请先使用最少的非行为型代码/配置更改集成该路径。
使用框架原生的生成器/导出路径提取规范，而非手动编写
```
openapi.yaml
```
。
将提取的规范保存到代码仓库。
检查生成的规范是否存在明显缺陷，如错误的状态码、通用的
```
*/*
```
内容类型、缺失的安全配置、薄弱的请求/响应架构以及缺失的错误响应。
优先使用源代码注释/配置进行优化。只有当源代码级修复无法表达所需契约时，才使用覆盖层。允许的优化：注释、装饰器、文档说明、提取工具配置和覆盖层更新。未经用户明确批准禁止的优化：实现更改、行为更改、签名更改、仅为调整契约而进行的数据模型更改或业务逻辑编辑。
每次有意义的优化后，重新提取规范。
使用此技能文档中记录的
```
docker pull
```
、
```
docker run
```
、验证和测试命令尝试Specmatic反馈循环。
如果Docker命令因Docker特定原因失败，请停止并准确询问用户：
```
Please confirm if docker engine is running
```
准备此技能的最终交付物，包括
```
run_contract_tests.sh
```
和
```
CONTRACT_TESTS_README.md
```
，无论是否需要确定性数据设置。
如果Docker不可用，仅在明确报告提取和优化已完成、可运行脚本和README已准备好，且下一步被阻塞的是实时Specmatic循环后，才停止任务。

不要仅将注释清理视为完整的提取后工作流。除非用户明确要求仅进行提取，否则不要在导出

openapi.yaml

后结束任务。如果规范主要是通过框架生成器/导出路径以外的手动方式编写的，不要声称规范已“提取”。

When to Use

适用场景

User has an existing API application, service, or repository and wants to generate an OpenAPI or Swagger specification from it
User asks to generate or extract an OpenAPI specification for "this application", "this project", "this service", or "this codebase"
User asks to derive, infer, reverse-engineer, document, or generate API docs/schema/contract from existing code or routes
User asks for Swagger docs, OpenAPI docs, API schema, or API contract for an existing implementation
User asks to create API schema, API docs, or Swagger docs from routes, controllers, annotations, or source code
User mentions a specific framework covered below

用户拥有现有API应用、服务或代码仓库，并希望从中生成OpenAPI或Swagger规范
用户要求为“此应用”、“此项目”、“此服务”或“此代码库”生成或提取OpenAPI规范
用户要求从现有代码或路由中推导、推断、逆向工程、文档化或生成API文档/架构/契约
用户要求为现有实现生成Swagger文档、OpenAPI文档、API架构或API契约
用户要求从路由、控制器、注释或源代码创建API架构、API文档或Swagger文档
用户提及以下涵盖的特定框架

Inputs

输入参数

Input	Required	Description
Framework	Yes	The API framework in use
Project path	Yes	Root directory of the API project
Output path	No	Where to write the spec (default: `openapi.yaml` )

输入项	是否必填	描述
Framework	是	使用的API框架
Project path	是	API项目的根目录
Output path	否	规范的写入路径（默认值： `openapi.yaml` ）

Outputs

输出结果

Output	Description
OpenAPI spec	Extracted JSON or YAML contract
Refined source metadata	Annotation/config updates used to improve regenerated output
Contract test runner	Runnable `run_contract_tests.sh` for the full suite, with optional setup hook
Contract test README	`CONTRACT_TESTS_README.md` describing how to run the generated script

输出项	描述
OpenAPI spec	提取的JSON或YAML契约
Refined source metadata	用于改进重新生成输出的注释/配置更新
Contract test runner	用于全套测试的可运行 `run_contract_tests.sh` ，可选包含设置钩子
Contract test README	`CONTRACT_TESTS_README.md` ，描述如何运行生成的脚本

Prerequisites

前置条件

The API project must be buildable and its dependencies installed
For runtime extraction, the app must be importable or startable

API项目必须可构建且已安装依赖
对于运行时提取，应用必须可导入或启动

Decision Framework

决策框架

Framework rule:

For every framework listed below, use the listed extraction method as the required path.
If the repo does not yet have the needed package, plugin, annotations, endpoint, config, or export script, add the minimum non-behavioral integration required to enable that extraction method, then run it.
Only fall back to non-framework-specific/manual derivation when the framework is not covered by this skill or the user explicitly forbids the required integration changes.

Framework	Method	Open this guide
FastAPI	Built-in export	content/frameworks/fastapi.md
Flask	CLI/programmatic export	content/frameworks/flask.md
Django REST Framework	`drf-spectacular` CLI	content/frameworks/django.md
Spring Boot	Runtime docs endpoint	content/frameworks/spring-boot.md
ASP.NET Core	Runtime docs endpoint	content/frameworks/aspnet.md
Express	`swagger-jsdoc`	content/frameworks/express.md
NestJS	Runtime docs endpoint or script	content/frameworks/nestjs.md
Hono	Programmatic export	content/frameworks/hono.md
Rails	`rswag` task	content/frameworks/rails.md
Laravel	`l5-swagger` command	content/frameworks/laravel.md

框架规则：

对于以下列出的每个框架，使用列出的提取方法作为必填路径。
如果代码库尚未具备所需的包、插件、注释、端点、配置或导出脚本，请添加启用该提取方法所需的最少非行为型集成，然后运行它。
仅当框架未被此技能覆盖或用户明确禁止所需的集成更改时，才回退到非框架特定/手动推导方式。

Framework	方法	打开此指南
FastAPI	内置导出	content/frameworks/fastapi.md
Flask	CLI/程序化导出	content/frameworks/flask.md
Django REST Framework	`drf-spectacular` CLI工具	content/frameworks/django.md
Spring Boot	运行时文档端点	content/frameworks/spring-boot.md
ASP.NET Core	运行时文档端点	content/frameworks/aspnet.md
Express	`swagger-jsdoc`	content/frameworks/express.md
NestJS	运行时文档端点或脚本	content/frameworks/nestjs.md
Hono	程序化导出	content/frameworks/hono.md
Rails	`rswag` 任务	content/frameworks/rails.md
Laravel	`l5-swagger` 命令	content/frameworks/laravel.md

Reference Routing

参考路由

Use the smallest amount of reference material needed.

For extraction: Open only the matching framework guide from
```
content/frameworks/
```
.
After the first extraction succeeds: Open content/specmatic-loop.md.
When generating
```
specmatic.yaml
```
, examples, overlays, or deterministic setup: Open content/specmatic-setup.md.
When preparing final scripts, docs, or acceptance checks: Open content/specmatic-deliverables.md.

Do not bulk-read all reference files. Identify the framework first, then open only the file needed for the current phase.

使用最少必要的参考资料。

提取阶段：仅打开
```
content/frameworks/
```
中匹配的框架指南。
首次提取成功后：打开content/specmatic-loop.md。
生成
```
specmatic.yaml
```
、示例、覆盖层或确定性设置时：打开content/specmatic-setup.md。
准备最终脚本、文档或验收检查时：打开content/specmatic-deliverables.md。

不要批量读取所有参考文件。先识别框架，然后仅打开当前阶段所需的文件。

Specmatic References

Specmatic参考资料

content/specmatic-loop.md: post-extraction loop, Docker gate, batching, and fix order
content/specmatic-setup.md:
```
specmatic.yaml
```
, overlays, examples, licensing, and deterministic setup
content/specmatic-deliverables.md: final scripts, README expectations, acceptance checks, and troubleshooting

content/specmatic-loop.md：提取后循环、Docker网关、批处理和修复顺序
content/specmatic-setup.md：
```
specmatic.yaml
```
、覆盖层、示例、许可和确定性设置
content/specmatic-deliverables.md：最终脚本、README要求、验收检查和故障排除