skills.rest
IgorSasovets
IgorSasovetsCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

openapi-spec-builder

Assembles reconnaissance artifacts into a complete OpenAPI 3.0.3 specification file.

9|2|Updated Jul 15, 2026
Search Tags:#openapi#API security#yaml#spec generation#REST API#swagger#API documentation
One-click install
npx skills add https://github.com/IgorSasovets/devsecops-with-claude --skill openapi-spec-builder-igorsasovets
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: openapi-spec-builder
Source: https://github.com/IgorSasovets/devsecops-with-claude/tree/main/openapi-spec-creator/.claude/skills/OPENAPI_SPEC_BUILDER
Command: npx skills add https://github.com/IgorSasovets/devsecops-with-claude --skill openapi-spec-builder-igorsasovets

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Manually writing an OpenAPI specification for an existing API is slow and error-prone, especially when routes, auth schemes, and schemas must be gathered from source code or a running application. This Skill consumes the structured artifacts produced by Stage 1 reconnaissance and assembles a valid openapi.yaml without re-reading the entire codebase. ## Core Features & Use Cases - Artifact-driven spec assembly: Reads routes.json, auth-map.md, schemas.md, validators.md, and dataflows.md from /openapi-source-recon or /openapi-devtools-scan, then builds paths, tags, security schemes, and component schemas. - Merge-aware generation: If an openapi.yaml already exists, it adds new paths and updates changed ones while preserving manual edits, or overwrites entirely when requested. - Self-validation: Runs a Python structural check for YAML validity, unresolved $ref values, duplicate operationIds, and missing required fields, inserting placeholder schemas where extraction was incomplete. - Use Case: After running /openapi-source-recon on an Express.js project, invoke this Skill to produce a complete openapi.yaml plus a human-readable spec-summary.md ready for import into Postman, Swagger UI, or Burp Suite. ## Quick Start Run /openapi-spec-builder on my project directory to generate the openapi.yaml from the recon artifacts.

Frequently Asked Questions about openapi-spec-builder

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate an OpenAPI spec from an existing API codebase?▼

Run a reconnaissance stage first (/openapi-source-recon for source code or /openapi-devtools-scan for a running app) to produce routes.json and related artifacts, then run /openapi-spec-builder with the target directory to assemble openapi.yaml.

What OpenAPI version does the generated spec use?▼

The generated spec uses OpenAPI 3.0.3, chosen for broad tooling compatibility with Burp Suite, OWASP ZAP, Postman, Swagger UI, and Redoc. Fields specific to 3.1.0 such as webhooks are not used.

Can I merge new routes into an existing openapi.yaml?▼

Yes. Merge mode adds new paths and schemas to an existing openapi.yaml while preserving manual edits, existing info, servers, and security blocks. Use --merge to force it or --overwrite to replace the file entirely.

What happens if schema extraction was incomplete?▼

The builder writes placeholder schemas with additionalProperties: true for any unresolved $ref values, so the spec remains valid OpenAPI 3.0.3. Placeholders are flagged with TODO descriptions and listed in spec-summary.md for manual enrichment.

How are authentication schemes mapped into the OpenAPI spec?▼

Detected schemes from auth-map.md are mapped to OpenAPI securityScheme objects: Bearer JWT becomes http/bearer, API keys become apiKey in header, query, or cookie, and OAuth2 flows include tokenUrl placeholders. A global security block is applied when over 80% of routes require auth.

Why does the spec builder fail with routes.json not found?▼

routes.json is the required spine of the spec and is only produced by Stage 1. Run /openapi-source-recon or /openapi-devtools-scan first, then re-run the builder against the same target directory.

Related Skills

Explore More Software Engineering Skills→
ThrookieThrookie
2

api-pattern-extractor

Extract API patterns from captured traffic or HAR files into OpenAPI specifications and structured pattern files.

Community
Intermediate
navraj007innavraj007in
2

export-openapi

Convert blueprint API specifications into downloadable OpenAPI 3.0 documents.

Community
Basic
BRANDNEWSHVTBRANDNEWSHVT

api-design-audit

Audit API designs for contracts, error handling, and documentation standards.

Official
Advanced
hekinamihekinami
1

weapp-reverse-engineering

Generate architecture documents, Mermaid ER diagrams, and OpenAPI specs from Django codebases.

Community
Intermediate