OpenAPI Spec Validator & Docs Generator
Validates OpenAPI 3.0/3.1 specifications using Spectral linting rules and generates interactive API documentation with Redoc and Swagger UI. Supports custom ruleset definitions and CI integration.
npx skills add agentskillexchange/skills --skill openapi-spec-validator-docs-generator
The OpenAPI Spec Validator and Docs Generator skill provides comprehensive validation of OpenAPI specifications and automated documentation generation. It uses Stoplight Spectral for linting with both built-in (oas) and custom rulesets, catching issues like missing descriptions, inconsistent error response schemas, and security scheme gaps.
What this skill actually does
The validation engine checks structural correctness against the OpenAPI 3.0.x and 3.1.x JSON Schema definitions, validates $ref resolution across multi-file specifications, and enforces API design guidelines through configurable Spectral rulesets. Custom rules can enforce naming conventions, pagination patterns, and versioning strategies specific to your organization.
For documentation generation, the skill produces both Redoc single-page HTML documentation and Swagger UI interactive explorers. It supports x-codeSamples extensions for embedding language-specific request examples, x-logo for branding, and webhook documentation for event-driven APIs. The skill integrates with CI pipelines by providing exit codes for lint severity levels and generating diff reports between specification versions using openapi-diff to track breaking changes.