skills.rest
erraggy
erraggyCOMMUNITY
Explore all skills by this author →
Website𝕏@erraggyGitHub

fix-spec

Preview and apply fixes for OpenAPI schema names, refs, and operationIds.

5|5|Updated Nov 9, 2025
Search Tags:#automation#openapi#validation#schema#api-spec#ref-resolution#operationid
One-click install
npx skills add https://github.com/erraggy/oastools --skill fix-spec
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: fix-spec
Source: https://github.com/erraggy/oastools/tree/main/plugin/skills/fix-spec
Command: npx skills add https://github.com/erraggy/oastools --skill fix-spec

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

OpenAPI specs often suffer from naming inconsistencies, missing refs, and duplicated operationIds. The Fix-spec tool provides a preview-first workflow to auto-fix common OpenAPI issues safely.

Core Features & Use Cases

  • Preview-first approach shows planned changes without modifying the original file
  • Auto-fix options include fix_schema_names, fix_duplicate_operationids, prune, stub_missing_refs
  • Validate and summarize changes before applying, then persist and re-validate the result
  • Use cases include preparing specs for release, refactoring schemas, and aligning operationIds

Quick Start

Run the fix-spec tool on your OpenAPI document to preview and apply fixes with a dry run first.

Frequently Asked Questions about fix-spec

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

FAQPage Schema
How do I auto-fix duplicate operationIds and invalid schema names in an OpenAPI spec?▼

Use a preview-first workflow to auto-fix duplicate operationIds and schema names in an OpenAPI spec. It shows planned changes before applying them, using flags like fix_schema_names and fix_duplicate_operationids to control the cleanup safely.

Can I preview OpenAPI spec fixes before applying them to the file?▼

Yes, you can preview OpenAPI spec fixes through a dry-run that validates and summarizes changes without modifying the original file. You then control persistence and re-validate the result after applying the fixes.

How do I resolve missing refs in an OpenAPI document during development?▼

Resolve missing refs in an OpenAPI document by enabling the stub_missing_refs flag. This automatically generates stubs for missing references, and you can verify the changes in a dry-run preview before persisting them.

Does fix-spec support pruning unused schemas from an OpenAPI spec?▼

Yes, fix-spec supports pruning unused schemas from an OpenAPI spec via the prune flag. You can validate the pruned output in a preview dry-run before applying the changes to ensure safe refactoring.

What is the best way to clean up an OpenAPI spec for release?▼

The best way to clean up an OpenAPI spec for release is using a deterministic, preview-first workflow. Apply auto-fix options like fix_schema_names and prune in a dry run, validate the summary, then persist and re-validate the result.

Why does OpenAPI validation fail on inconsistent schema names and how can I fix it?▼

OpenAPI validation fails on inconsistent schema names due to naming collisions or formatting issues. Fix this automatically by running the fix_schema_names flag in a preview dry-run to see the corrected names before applying them.

Related Skills

Explore More Software Engineering Skills→
gestrichgestrich

domain-modeling

Design domain models that parse YAML, JSON, or Markdown into typed objects.

Community
Advanced
PlaneInABottlePlaneInABottle

api-contract-testing

Validate REST API contracts against OpenAPI specifications and JSON Schema.

Community
Intermediate
mk-knight23mk-knight23
1

api-tester

Generate and execute pytest suites from OpenAPI specs for REST APIs.

Community
Advanced
seabbsseabbs
7

lint

Lint and format code across languages with Git integration.

Community
Intermediate