OpenAPI验证器Skill openapi-validator

---

name: openapi-validator description: 验证OpenAPI规范的正确性、安全性和最佳实践 allowed-tools:

• Bash
• Read
• Write
• Glob

---

OpenAPI验证器技能

概述

验证OpenAPI规范的正确性、安全定义、最佳实践合规性以及版本间的破坏性变更检测。

能力

• 验证OpenAPI 3.0/3.1规范
• 检查安全定义的完整性
• 针对API设计最佳实践进行代码检查
• 比较规范版本
• 检测版本间的破坏性变更
• 自定义规则配置
• 与Spectral和其他代码检查工具集成

目标流程

• api-design-specification
• system-design-review

输入模式

{
  "type": "object",
  "required": ["specPath"],
  "properties": {
    "specPath": {
      "type": "string",
      "description": "OpenAPI规范文件的路径"
    },
    "mode": {
      "type": "string",
      "enum": ["validate", "lint", "compare", "security"],
      "default": "validate"
    },
    "compareWith": {
      "type": "string",
      "description": "用于比较的先前规范版本的路径"
    },
    "rules": {
      "type": "object",
      "properties": {
        "ruleset": {
          "type": "string",
          "enum": ["spectral:oas", "custom"],
          "default": "spectral:oas"
        },
        "severity": {
          "type": "string",
          "enum": ["error", "warn", "info"],
          "default": "warn"
        }
      }
    }
  }
}

输出模式

{
  "type": "object",
  "properties": {
    "valid": {
      "type": "boolean"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "message": { "type": "string" },
          "severity": { "type": "string" }
        }
      }
    },
    "warnings": {
      "type": "array"
    },
    "breakingChanges": {
      "type": "array",
      "description": "比较时发现的破坏性变更列表"
    },
    "securityIssues": {
      "type": "array"
    }
  }
}

使用示例

{
  kind: 'skill',
  skill: {
    name: 'openapi-validator',
    context: {
      specPath: 'api/openapi.yaml',
      mode: 'lint',
      rules: {
        ruleset: 'spectral:oas',
        severity: 'warn'
      }
    }
  }
}