specmatic-openapi-spec-extractor（Specmatic openapi 规范提取器）

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.

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.

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

Docker Execution Rule

• 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.

Mandatory Post-Extraction Workflow

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

1. 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.
2. Extract the spec using the framework-native generator/export path, not by manually writing openapi.yaml.
3. Save the extracted spec to the repo.
4. 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.
5. 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.
6. Re-extract the spec after each meaningful refinement.
7. Attempt the Specmatic feedback loop using the documented docker pull, docker run, validation, and test commands from this skill.
8. If a Docker command fails for a Docker-specific reason, stop and ask the user exactly: Please confirm if docker engine is running
9. 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.
10. 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.

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

Inputs

Outputs

Prerequisites

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

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.

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.

Specmatic References

• 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