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 , , 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 , 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.
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 .
- 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 , , 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 and , 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
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
| 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: ) |
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 for the full suite, with optional setup hook |
| Contract test README | describing how to run the generated script |
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.
| Framework | Method | Open this guide |
|---|
| FastAPI | Built-in export | content/frameworks/fastapi.md |
| Flask | CLI/programmatic export | content/frameworks/flask.md |
| Django REST Framework | 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 | | content/frameworks/express.md |
| NestJS | Runtime docs endpoint or script | content/frameworks/nestjs.md |
| Hono | Programmatic export | content/frameworks/hono.md |
| Rails | task | content/frameworks/rails.md |
| Laravel | command | content/frameworks/laravel.md |
Reference Routing
Use the smallest amount of reference material needed.
- For extraction:
Open only the matching framework guide from .
- After the first extraction succeeds:
Open content/specmatic-loop.md.
- When generating , 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: , overlays, examples, licensing, and deterministic setup
- content/specmatic-deliverables.md: final scripts, README expectations, acceptance checks, and troubleshooting