OpenAPI安全规范与自动扫描最佳实践

一、模型与输入type SecurityScheme = { type: 'http' | 'apiKey' | 'oauth2'; name?: string; scheme?: string } type Operation = { security?: string[]; parameters?: { name: string; in: 'query' | 'header' | 'path' | 'cookie'; required?: boolean; schema?: { type: 'string' | 'number' | 'boolean'; min?: number; max?: number } }[] } type PathItem = { [method: string]: Operation } type OpenApiDoc = { securitySchemes: Record<string, SecurityScheme>; paths: Record<string, PathItem> } 二、校验规则function hasSecurity(doc: OpenApiDoc, op: Operation): boolean { const list = op.security || [] return list.every(k => !!doc.securitySchemes[k]) } function validParam(p: Operation['parameters'][number]): boolean { const s = p.schema if (!s) return false if (s.type === 'string') return true if (s.type === 'number') return typeof s.min === 'number' && typeof s.max === 'number' && s.min <= s.max if (s.type === 'boolean') return true return false } function requiredOk(p: Operation['parameters'][number]): boolean { if (p.in === 'path') return p.required === true return true } 三、扫描器与报告type Issue = { path: string; method: string; code: string; detail: string } function scan(doc: OpenApiDoc): Issue[] { const out: Issue[] = [] for (const [path, item] of Object.entries(doc.paths)) { for (const [method, op] of Object.entries(item)) { if (!hasSecurity(doc, op)) out.push({ path, method, code: 'missing_security', detail: 'operation without security' }) for (const p of op.parameters || []) { if (!requiredOk(p)) out.push({ path, method, code: 'path_param_required', detail: p.name }) if (!validParam(p)) out.push({ path, method, code: 'param_invalid', detail: p.name }) } } } return out } 四、聚合与验收class Aggregator { counts = new Map<string, number>(); inc(k: string) { const n = (this.counts.get(k) || 0) + 1; this.counts.set(k, n) } top() { return Array.from(this.counts.entries()).sort((a,b)=>b[1]-a[1]) } } function aggregate(issues: Issue[]): Aggregator { const agg = new Aggregator(); for (const i of issues) agg.inc(i.code); return agg } 所有操作声明安全方案并存在；路径参数标记`required=true`；数字参数具备最小最大范围。报告聚合包含问题码与计数；输出按路径与方法可定位；可作为CI检查的一部分。