499 lines
14 KiB
JavaScript
499 lines
14 KiB
JavaScript
#!/usr/bin/env node
|
|
/**
|
|
* OpenAPI Spec Validator
|
|
*
|
|
* Validates OpenAPI YAML files for:
|
|
* - Valid YAML syntax
|
|
* - Required OpenAPI structure (info, paths, etc.)
|
|
* - Common issues: missing descriptions, missing response codes
|
|
* - Consistent naming conventions
|
|
* - Resolvable schema references
|
|
*
|
|
* Usage:
|
|
* npx tsx scripts/validate-openapi-spec.ts
|
|
*
|
|
* Exit codes:
|
|
* 0 - All specs valid
|
|
* 1 - Validation errors found
|
|
*/
|
|
|
|
import * as fs from "fs";
|
|
import * as path from "path";
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Types
|
|
// ---------------------------------------------------------------------------
|
|
|
|
interface ValidationIssue {
|
|
severity: "error" | "warning";
|
|
path: string;
|
|
message: string;
|
|
}
|
|
|
|
interface ParsedSpec {
|
|
openapi?: string;
|
|
info?: { title?: string; version?: string; description?: string };
|
|
paths?: Record<string, Record<string, any>>;
|
|
components?: {
|
|
schemas?: Record<string, any>;
|
|
securitySchemes?: Record<string, any>;
|
|
};
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Simple YAML parser (enough for OpenAPI validation without dependencies)
|
|
// ---------------------------------------------------------------------------
|
|
|
|
function parseYAML(content: string): ParsedSpec {
|
|
const result: any = {};
|
|
const lines = content.split("\n");
|
|
const stack: Array<{ indent: number; obj: any; key?: string }> = [
|
|
{ indent: -1, obj: result },
|
|
];
|
|
|
|
for (let i = 0; i < lines.length; i++) {
|
|
const line = lines[i];
|
|
|
|
// Skip empty lines and comments
|
|
if (/^\s*$/.test(line) || /^\s*#/.test(line)) continue;
|
|
|
|
const indentMatch = line.match(/^(\s*)/);
|
|
const indent = indentMatch ? indentMatch[1].length : 0;
|
|
const trimmed = line.trim();
|
|
|
|
// Pop stack until we find the right parent
|
|
while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
|
|
stack.pop();
|
|
}
|
|
|
|
const parent = stack[stack.length - 1];
|
|
|
|
// Match key: value
|
|
const kvMatch = trimmed.match(/^([^:]+?):\s*(.*)$/);
|
|
if (kvMatch) {
|
|
const key = kvMatch[1].trim().replace(/^["']|["']$/g, "");
|
|
const value = kvMatch[2].trim();
|
|
|
|
if (value === "" || value === "|" || value === ">") {
|
|
// Object or block scalar
|
|
const newObj: any = {};
|
|
if (Array.isArray(parent.obj)) {
|
|
parent.obj.push({ [key]: newObj });
|
|
} else {
|
|
parent.obj[key] = newObj;
|
|
}
|
|
stack.push({ indent, obj: newObj, key });
|
|
} else {
|
|
// Simple value
|
|
let parsedValue: any = value;
|
|
if (value === "true") parsedValue = true;
|
|
else if (value === "false") parsedValue = false;
|
|
else if (/^\d+$/.test(value)) parsedValue = parseInt(value, 10);
|
|
else parsedValue = value.replace(/^["']|["']$/g, "");
|
|
|
|
if (Array.isArray(parent.obj)) {
|
|
parent.obj.push({ [key]: parsedValue });
|
|
} else {
|
|
parent.obj[key] = parsedValue;
|
|
}
|
|
}
|
|
} else if (trimmed.startsWith("- ")) {
|
|
// Array item
|
|
const itemValue = trimmed.slice(2).trim();
|
|
if (!Array.isArray(parent.obj)) {
|
|
// Convert parent's value to array
|
|
const parentParent = stack.length > 1 ? stack[stack.length - 2] : null;
|
|
if (parentParent && parent.key) {
|
|
const arr: any[] = [];
|
|
parentParent.obj[parent.key] = arr;
|
|
parent.obj = arr;
|
|
}
|
|
}
|
|
if (Array.isArray(parent.obj)) {
|
|
parent.obj.push(itemValue.replace(/^["']|["']$/g, ""));
|
|
}
|
|
}
|
|
}
|
|
|
|
return result;
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Validation rules
|
|
// ---------------------------------------------------------------------------
|
|
|
|
function validateSpecStructure(content: string, filePath: string): ValidationIssue[] {
|
|
const issues: ValidationIssue[] = [];
|
|
const fileName = path.basename(filePath);
|
|
|
|
// Check YAML can be parsed without errors
|
|
let spec: ParsedSpec;
|
|
try {
|
|
spec = parseYAML(content);
|
|
} catch (err: any) {
|
|
issues.push({
|
|
severity: "error",
|
|
path: fileName,
|
|
message: `YAML parse error: ${err.message}`,
|
|
});
|
|
return issues;
|
|
}
|
|
|
|
// Check required top-level fields
|
|
if (!spec.openapi) {
|
|
issues.push({
|
|
severity: "error",
|
|
path: `${fileName}/openapi`,
|
|
message: "Missing required field: openapi (version string)",
|
|
});
|
|
} else if (!spec.openapi.toString().startsWith("3.")) {
|
|
issues.push({
|
|
severity: "warning",
|
|
path: `${fileName}/openapi`,
|
|
message: `OpenAPI version ${spec.openapi} may not be widely supported. Consider 3.0.x or 3.1.x`,
|
|
});
|
|
}
|
|
|
|
if (!spec.info) {
|
|
issues.push({
|
|
severity: "error",
|
|
path: `${fileName}/info`,
|
|
message: "Missing required field: info",
|
|
});
|
|
} else {
|
|
if (!spec.info.title) {
|
|
issues.push({
|
|
severity: "error",
|
|
path: `${fileName}/info/title`,
|
|
message: "Missing required field: info.title",
|
|
});
|
|
}
|
|
if (!spec.info.version) {
|
|
issues.push({
|
|
severity: "error",
|
|
path: `${fileName}/info/version`,
|
|
message: "Missing required field: info.version",
|
|
});
|
|
}
|
|
if (!spec.info.description) {
|
|
issues.push({
|
|
severity: "warning",
|
|
path: `${fileName}/info/description`,
|
|
message: "Missing recommended field: info.description",
|
|
});
|
|
}
|
|
}
|
|
|
|
if (!spec.paths || Object.keys(spec.paths).length === 0) {
|
|
issues.push({
|
|
severity: "error",
|
|
path: `${fileName}/paths`,
|
|
message: "No paths defined in spec",
|
|
});
|
|
}
|
|
|
|
return issues;
|
|
}
|
|
|
|
function validatePaths(content: string, filePath: string): ValidationIssue[] {
|
|
const issues: ValidationIssue[] = [];
|
|
const fileName = path.basename(filePath);
|
|
const lines = content.split("\n");
|
|
|
|
let inPaths = false;
|
|
let currentPath = "";
|
|
let currentMethod = "";
|
|
let pathIndent = -1;
|
|
let hasResponses = false;
|
|
let hasSummary = false;
|
|
let hasOperationId = false;
|
|
let methodStartLine = 0;
|
|
|
|
const operationIds = new Set<string>();
|
|
const pathsFound = new Set<string>();
|
|
|
|
for (let i = 0; i < lines.length; i++) {
|
|
const line = lines[i];
|
|
const trimmed = line.trim();
|
|
|
|
if (/^paths:\s*$/.test(trimmed)) {
|
|
inPaths = true;
|
|
pathIndent = -1;
|
|
continue;
|
|
}
|
|
|
|
if (!inPaths) continue;
|
|
|
|
// End of paths section
|
|
if (/^\S/.test(line) && !line.startsWith(" ") && !line.startsWith("#") && trimmed !== "") {
|
|
inPaths = false;
|
|
continue;
|
|
}
|
|
|
|
// Detect path entry
|
|
const pathMatch = trimmed.match(/^(\/[^:]*)\s*:\s*$/);
|
|
if (pathMatch && line.match(/^\s{2}\//)) {
|
|
// Save previous method check
|
|
if (currentMethod && !hasResponses) {
|
|
issues.push({
|
|
severity: "warning",
|
|
path: `${fileName}#${currentPath}/${currentMethod}`,
|
|
message: `Missing responses for ${currentMethod.toUpperCase()} ${currentPath}`,
|
|
});
|
|
}
|
|
|
|
currentPath = pathMatch[1].trim();
|
|
currentMethod = "";
|
|
hasResponses = false;
|
|
hasSummary = false;
|
|
hasOperationId = false;
|
|
|
|
if (pathsFound.has(currentPath)) {
|
|
issues.push({
|
|
severity: "error",
|
|
path: `${fileName}#${currentPath}`,
|
|
message: `Duplicate path: ${currentPath}`,
|
|
});
|
|
}
|
|
pathsFound.add(currentPath);
|
|
|
|
// Check path naming convention
|
|
if (/[A-Z]/.test(currentPath) && !currentPath.includes("{")) {
|
|
issues.push({
|
|
severity: "warning",
|
|
path: `${fileName}#${currentPath}`,
|
|
message: `Path contains uppercase characters. Use lowercase with hyphens for consistency.`,
|
|
});
|
|
}
|
|
|
|
continue;
|
|
}
|
|
|
|
// Detect HTTP method
|
|
const methodMatch = trimmed.match(/^(get|post|put|patch|delete)\s*:\s*$/);
|
|
if (methodMatch && currentPath) {
|
|
// Save previous method check
|
|
if (currentMethod && !hasResponses) {
|
|
issues.push({
|
|
severity: "warning",
|
|
path: `${fileName}#${currentPath}/${currentMethod}`,
|
|
message: `Missing responses for ${currentMethod.toUpperCase()} ${currentPath}`,
|
|
});
|
|
}
|
|
|
|
currentMethod = methodMatch[1];
|
|
methodStartLine = i;
|
|
hasResponses = false;
|
|
hasSummary = false;
|
|
hasOperationId = false;
|
|
continue;
|
|
}
|
|
|
|
// Check for summary
|
|
if (currentMethod && trimmed.startsWith("summary:")) {
|
|
hasSummary = true;
|
|
const summary = trimmed.replace(/^summary:\s*/, "").replace(/^["']|["']$/g, "");
|
|
if (summary.length === 0) {
|
|
issues.push({
|
|
severity: "warning",
|
|
path: `${fileName}#${currentPath}/${currentMethod}`,
|
|
message: `Empty summary for ${currentMethod.toUpperCase()} ${currentPath}`,
|
|
});
|
|
}
|
|
}
|
|
|
|
// Check for operationId
|
|
if (currentMethod && trimmed.startsWith("operationId:")) {
|
|
hasOperationId = true;
|
|
const opId = trimmed.replace(/^operationId:\s*/, "").replace(/^["']|["']$/g, "");
|
|
if (operationIds.has(opId)) {
|
|
issues.push({
|
|
severity: "error",
|
|
path: `${fileName}#${currentPath}/${currentMethod}`,
|
|
message: `Duplicate operationId: ${opId}`,
|
|
});
|
|
}
|
|
operationIds.add(opId);
|
|
}
|
|
|
|
// Check for responses
|
|
if (currentMethod && trimmed === "responses:") {
|
|
hasResponses = true;
|
|
}
|
|
}
|
|
|
|
// Check last method
|
|
if (currentMethod && !hasResponses) {
|
|
issues.push({
|
|
severity: "warning",
|
|
path: `${fileName}#${currentPath}/${currentMethod}`,
|
|
message: `Missing responses for ${currentMethod.toUpperCase()} ${currentPath}`,
|
|
});
|
|
}
|
|
|
|
return issues;
|
|
}
|
|
|
|
function validateSchemaRefs(content: string, filePath: string): ValidationIssue[] {
|
|
const issues: ValidationIssue[] = [];
|
|
const fileName = path.basename(filePath);
|
|
|
|
// Find all $ref references
|
|
const refRegex = /\$ref:\s*["']?#\/components\/schemas\/(\w+)["']?/g;
|
|
let match: RegExpExecArray | null;
|
|
const referencedSchemas = new Set<string>();
|
|
|
|
while ((match = refRegex.exec(content)) !== null) {
|
|
referencedSchemas.add(match[1]);
|
|
}
|
|
|
|
// Find all defined schemas
|
|
const definedSchemas = new Set<string>();
|
|
const schemaDefRegex = /^\s{4}(\w+):\s*$/gm;
|
|
let inComponents = false;
|
|
let inSchemas = false;
|
|
|
|
const lines = content.split("\n");
|
|
for (const line of lines) {
|
|
const trimmed = line.trim();
|
|
if (trimmed === "components:") {
|
|
inComponents = true;
|
|
continue;
|
|
}
|
|
if (inComponents && trimmed === "schemas:") {
|
|
inSchemas = true;
|
|
continue;
|
|
}
|
|
if (inSchemas && /^\s{4}\w+:/.test(line)) {
|
|
const schemaName = line.trim().replace(/:.*$/, "");
|
|
definedSchemas.add(schemaName);
|
|
}
|
|
// End of schemas section
|
|
if (inSchemas && /^\s{2}\w+:/.test(line) && !line.trim().startsWith("-")) {
|
|
if (!line.match(/^\s{4}/)) {
|
|
inSchemas = false;
|
|
}
|
|
}
|
|
}
|
|
|
|
// Check for unresolvable references
|
|
for (const ref of referencedSchemas) {
|
|
if (!definedSchemas.has(ref)) {
|
|
issues.push({
|
|
severity: "error",
|
|
path: `${fileName}/components/schemas/${ref}`,
|
|
message: `Unresolvable schema reference: #/components/schemas/${ref}`,
|
|
});
|
|
}
|
|
}
|
|
|
|
// Check for unused schemas (warning only)
|
|
for (const schema of definedSchemas) {
|
|
if (!referencedSchemas.has(schema)) {
|
|
issues.push({
|
|
severity: "warning",
|
|
path: `${fileName}/components/schemas/${schema}`,
|
|
message: `Schema "${schema}" is defined but never referenced`,
|
|
});
|
|
}
|
|
}
|
|
|
|
return issues;
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------
|
|
// Main
|
|
// ---------------------------------------------------------------------------
|
|
|
|
interface SpecConfig {
|
|
name: string;
|
|
file: string;
|
|
}
|
|
|
|
const rootDir = path.resolve(__dirname, "..");
|
|
|
|
const specs: SpecConfig[] = [
|
|
{
|
|
name: "AITimeMachine API",
|
|
file: path.join(rootDir, "aitimemachine/api-server/docs/openapi.yaml"),
|
|
},
|
|
{
|
|
name: "Gitgram Backend",
|
|
file: path.join(rootDir, "gitgram/backend/docs/openapi.yaml"),
|
|
},
|
|
];
|
|
|
|
let totalErrors = 0;
|
|
let totalWarnings = 0;
|
|
|
|
for (const spec of specs) {
|
|
console.log(`\n${"=".repeat(80)}`);
|
|
console.log(` Validating: ${spec.name}`);
|
|
console.log(` File: ${spec.file}`);
|
|
console.log(`${"=".repeat(80)}`);
|
|
|
|
if (!fs.existsSync(spec.file)) {
|
|
console.log(` ERROR: File not found: ${spec.file}`);
|
|
totalErrors++;
|
|
continue;
|
|
}
|
|
|
|
const content = fs.readFileSync(spec.file, "utf-8");
|
|
|
|
// Run all validation checks
|
|
const allIssues: ValidationIssue[] = [
|
|
...validateSpecStructure(content, spec.file),
|
|
...validatePaths(content, spec.file),
|
|
...validateSchemaRefs(content, spec.file),
|
|
];
|
|
|
|
const errors = allIssues.filter((i) => i.severity === "error");
|
|
const warnings = allIssues.filter((i) => i.severity === "warning");
|
|
|
|
totalErrors += errors.length;
|
|
totalWarnings += warnings.length;
|
|
|
|
if (errors.length > 0) {
|
|
console.log(`\n ERRORS (${errors.length}):`);
|
|
for (const issue of errors) {
|
|
console.log(` [ERROR] ${issue.path}`);
|
|
console.log(` ${issue.message}`);
|
|
}
|
|
}
|
|
|
|
if (warnings.length > 0) {
|
|
console.log(`\n WARNINGS (${warnings.length}):`);
|
|
for (const issue of warnings) {
|
|
console.log(` [WARN] ${issue.path}`);
|
|
console.log(` ${issue.message}`);
|
|
}
|
|
}
|
|
|
|
if (errors.length === 0 && warnings.length === 0) {
|
|
console.log(`\n All checks passed.`);
|
|
}
|
|
|
|
// Count paths and methods
|
|
const pathRegex = /^\s{2}\/[^:]+:\s*$/gm;
|
|
const methodRegex = /^\s{4}(get|post|put|patch|delete):\s*$/gm;
|
|
const pathCount = (content.match(pathRegex) || []).length;
|
|
const methodCount = (content.match(methodRegex) || []).length;
|
|
|
|
console.log(`\n Stats: ${pathCount} paths, ${methodCount} operations`);
|
|
}
|
|
|
|
// Summary
|
|
console.log(`\n${"=".repeat(80)}`);
|
|
console.log(" VALIDATION SUMMARY");
|
|
console.log(`${"=".repeat(80)}`);
|
|
console.log(` Errors: ${totalErrors}`);
|
|
console.log(` Warnings: ${totalWarnings}`);
|
|
|
|
if (totalErrors > 0) {
|
|
console.log(`\n FAIL: ${totalErrors} error(s) found. Fix errors before merging.\n`);
|
|
process.exit(1);
|
|
} else {
|
|
console.log(`\n PASS: All OpenAPI specs are structurally valid.\n`);
|
|
process.exit(0);
|
|
}
|