validate-openapi-spec
9
总安装量
9
周安装量
#32911
全站排名
安装命令
npx skills add https://github.com/speakeasy-api/agent-skills --skill validate-openapi-spec
Agent 安装分布
claude-code
8
antigravity
7
codex
7
windsurf
6
gemini-cli
6
Skill 文档
validate-openapi-spec
Use speakeasy lint to check for errors and warnings in your OpenAPI spec.
When to Use
- Checking if a spec is valid before generation
- Identifying errors blocking SDK generation
- User says: “validate spec”, “lint spec”, “is my spec valid”
Inputs
| Input | Required | Description |
|---|---|---|
| OpenAPI spec | Yes | Path to spec file (-s) |
Outputs
| Output | Description |
|---|---|
| Errors | Issues that block SDK generation |
| Warnings | Issues that may cause problems |
| Hints | Best practice suggestions |
Command
speakeasy lint openapi --non-interactive -s <path-to-spec>
Output Categories
| Severity | Meaning | Action |
|---|---|---|
| Error | Blocks SDK generation | Must fix |
| Warning | May cause issues | Should fix |
| Hint | Best practice suggestion | Consider fixing |
Common Validation Issues
| Issue | Solution |
|---|---|
| Missing operationId | Add operationId or use speakeasy suggest operation-ids |
| Invalid $ref | Fix the reference path |
| Missing response schema | Add response schema definitions |
| Duplicate operationId | Make operation IDs unique |
AI-Friendly Output
For commands with large outputs, pipe to grep or tail to reduce context:
speakeasy lint openapi --non-interactive -s ./openapi.yaml 2>&1 | grep -E "(error|warning)"
What NOT to Do
- Do NOT fix errors one-by-one without understanding root cause
- Do NOT ignore warnings – they often indicate real problems
- Do NOT modify the source spec without asking if it’s externally managed
Troubleshooting
| Error | Cause | Solution |
|---|---|---|
| “file not found” | Invalid spec path | Check the file path exists |
| Many duplicate errors | Shared schema issues | Fix the root schema, not each reference |
| “$ref not found” | Broken reference | Check the reference path matches actual location |
Related Skills
diagnose-generation-failure– When lint errors cause generation to failfix-validation-errors-with-overlays– Fix issues without modifying source specget-ai-suggestions– Get AI-powered suggestions for improvements