const fs = require('fs'); const yaml = require('js-yaml'); const OPENAPI_PATH = 'openapi.yml'; const PATCH_DIR = 'openapi-patches'; function fail(msg) { console.error(`patch-openapi: ${msg}`); process.exit(1); } function readPatch(path) { try { if (path.endsWith('.yml') || path.endsWith('.yaml')) { return yaml.load(fs.readFileSync(path, 'utf8')); } return JSON.parse(fs.readFileSync(path, 'utf8')); } catch (err) { fail(`Failed to read ${path}: ${err.message}`); } } function loadPatchTargets() { if (!fs.existsSync(PATCH_DIR)) { fail(`${PATCH_DIR} not found`); } const entries = fs .readdirSync(PATCH_DIR) .filter((name) => name.endsWith('.yml') || name.endsWith('.yaml')) .sort(); if (entries.length === 0) { fail(`No patch files found in ${PATCH_DIR}`); } const targets = []; for (const name of entries) { const patchPath = `${PATCH_DIR}/${name}`; const patch = readPatch(patchPath); if (!patch || !Array.isArray(patch.targets)) { fail(`${patchPath} must contain a top-level "targets" array`); } targets.push(...patch.targets); } return targets; } function getIndent(line) { const match = line.match(/^\s*/); return match ? match[0] : ''; } function insertLines(lines, index, newLines) { lines.splice(index, 0, ...newLines); } function findBlockEnd(lines, startIndex, baseIndent) { for (let i = startIndex + 1; i < lines.length; i++) { const line = lines[i]; if (line.trim() === '') continue; const indent = getIndent(line); if (indent.length <= baseIndent.length) return i; } return lines.length; } function ensureRequired(lines, schemaIndex, requiredList) { const schemaIndent = getIndent(lines[schemaIndex]); const blockEnd = findBlockEnd(lines, schemaIndex, schemaIndent); for (let i = schemaIndex + 1; i < blockEnd; i++) { if (lines[i].trim() === 'required:') return; } const requiredIndent = `${schemaIndent} `; const itemIndent = `${requiredIndent} `; const requiredLines = [ `${requiredIndent}required:`, ...requiredList.map((item) => `${itemIndent}- ${item}`) ]; insertLines(lines, schemaIndex + 1, requiredLines); } function ensureProperties(lines, schemaIndex, properties) { const schemaIndent = getIndent(lines[schemaIndex]); const blockEnd = findBlockEnd(lines, schemaIndex, schemaIndent); let propertiesIndex = -1; for (let i = schemaIndex + 1; i < blockEnd; i++) { if (lines[i].trim() === 'properties:') { propertiesIndex = i; break; } } const propertiesIndent = `${schemaIndent} `; const fieldIndent = `${propertiesIndent} `; const typeIndent = `${fieldIndent} `; if (propertiesIndex === -1) { const linesToAdd = [`${propertiesIndent}properties:`]; for (const [key, value] of Object.entries(properties)) { linesToAdd.push(`${fieldIndent}${key}:`); if (value && typeof value === 'object') { for (const [vk, vv] of Object.entries(value)) { linesToAdd.push(`${typeIndent}${vk}: ${vv}`); } } } insertLines(lines, schemaIndex + 1, linesToAdd); return; } const propertiesEnd = findBlockEnd(lines, propertiesIndex, getIndent(lines[propertiesIndex])); const existing = new Set(); for (let i = propertiesIndex + 1; i < propertiesEnd; i++) { const line = lines[i]; const indent = getIndent(line); if (indent.length !== fieldIndent.length) continue; const trimmed = line.trim(); if (trimmed.endsWith(':')) { existing.add(trimmed.slice(0, -1)); } } const toInsert = []; for (const [key, value] of Object.entries(properties)) { if (!existing.has(key)) { toInsert.push(`${fieldIndent}${key}:`); if (value && typeof value === 'object') { for (const [vk, vv] of Object.entries(value)) { toInsert.push(`${typeIndent}${vk}: ${vv}`); } } continue; } if (!value || typeof value !== 'object') continue; // Property exists; ensure missing fields like description/example are present. let propIndex = -1; for (let i = propertiesIndex + 1; i < propertiesEnd; i++) { if (lines[i].trim() === `${key}:` && getIndent(lines[i]).length === fieldIndent.length) { propIndex = i; break; } } if (propIndex === -1) continue; const propEnd = findBlockEnd(lines, propIndex, getIndent(lines[propIndex])); const present = new Set(); for (let i = propIndex + 1; i < propEnd; i++) { const line = lines[i]; const indent = getIndent(line); if (indent.length !== typeIndent.length) continue; const trimmed = line.trim(); const match = trimmed.match(/^([^:]+):/); if (match) present.add(match[1]); } const propInsert = []; for (const [vk, vv] of Object.entries(value)) { if (present.has(vk)) continue; propInsert.push(`${typeIndent}${vk}: ${vv}`); } if (propInsert.length > 0) { insertLines(lines, propIndex + 1, propInsert); } } if (toInsert.length > 0) insertLines(lines, propertiesIndex + 1, toInsert); } function patchTarget(lines, target) { const pathLine = `${target.path}:`; const methodLine = `${target.method}:`; let pathIndex = -1; for (let i = 0; i < lines.length; i++) { if (lines[i].trim() === pathLine) { pathIndex = i; break; } } if (pathIndex === -1) return false; let methodIndex = -1; for (let i = pathIndex + 1; i < lines.length; i++) { const line = lines[i]; if (line.trim() === methodLine) { methodIndex = i; break; } if (line.trim().endsWith(':') && getIndent(line).length <= 2) break; } if (methodIndex === -1) return false; let schemaIndex = -1; let inAppJson = false; for (let i = methodIndex + 1; i < lines.length; i++) { const line = lines[i]; if (line.trim().endsWith(':') && getIndent(line).length <= 4) break; if (line.trim() === 'application/json:') inAppJson = true; if (inAppJson && line.trim() === 'schema:') { schemaIndex = i; break; } } if (schemaIndex === -1) return false; if (target.schema?.required?.length) { ensureRequired(lines, schemaIndex, target.schema.required); } if (target.schema?.properties) { ensureProperties(lines, schemaIndex, target.schema.properties); } // Ensure requestBody examples include properties that define examples if (target.schema?.properties) { const exampleValues = {}; for (const [key, value] of Object.entries(target.schema.properties)) { if (value && typeof value === 'object' && value.example !== undefined) { exampleValues[key] = value.example; } } if (Object.keys(exampleValues).length > 0) { const examplesIndex = lines.findIndex( (line, idx) => idx > schemaIndex && line.trim() === 'examples:' && getIndent(line).length > getIndent(lines[schemaIndex]).length ); if (examplesIndex !== -1) { const examplesEnd = findBlockEnd(lines, examplesIndex, getIndent(lines[examplesIndex])); for (let i = examplesIndex + 1; i < examplesEnd; i++) { if (lines[i].trim() !== 'value:') continue; const valueIndent = getIndent(lines[i]); const valueEnd = findBlockEnd(lines, i, valueIndent); const present = new Set(); for (let j = i + 1; j < valueEnd; j++) { const line = lines[j]; if (getIndent(line).length !== valueIndent.length + 2) continue; const match = line.trim().match(/^([^:]+):/); if (match) present.add(match[1]); } const insertLinesArr = []; for (const [key, exampleVal] of Object.entries(exampleValues)) { if (present.has(key)) continue; const rendered = typeof exampleVal === 'string' ? `'${exampleVal}'` : `${exampleVal}`; insertLinesArr.push(`${valueIndent} ${key}: ${rendered}`); } if (insertLinesArr.length > 0) { insertLines(lines, i + 1, insertLinesArr); } } } } } if (Array.isArray(target.parameters) && target.parameters.length > 0) { ensureParameters(lines, methodIndex, target.parameters); } return true; } function ensureParameters(lines, methodIndex, params) { const methodIndent = getIndent(lines[methodIndex]); const methodEnd = findBlockEnd(lines, methodIndex, methodIndent); let paramsIndex = -1; for (let i = methodIndex + 1; i < methodEnd; i++) { if (lines[i].trim() === 'parameters:') { paramsIndex = i; break; } } if (paramsIndex === -1) return; const paramsEnd = findBlockEnd(lines, paramsIndex, getIndent(lines[paramsIndex])); for (const param of params) { const name = param.name; const location = param.in; if (!name || !location) continue; let entryIndex = -1; for (let i = paramsIndex + 1; i < paramsEnd; i++) { if (lines[i].trim() === `- name: ${name}`) { entryIndex = i; break; } } if (entryIndex === -1) continue; const entryEnd = findBlockEnd(lines, entryIndex, getIndent(lines[entryIndex])); let hasIn = false; let requiredIndex = -1; for (let i = entryIndex + 1; i < entryEnd; i++) { const trimmed = lines[i].trim(); if (trimmed === `in: ${location}`) hasIn = true; if (trimmed.startsWith('required:')) requiredIndex = i; } if (!hasIn) continue; const requiredLine = `${getIndent(lines[entryIndex])} required: ${param.required ? 'true' : 'false'}`; if (requiredIndex === -1) { insertLines(lines, entryIndex + 1, [requiredLine]); } else { lines[requiredIndex] = requiredLine; } } } function main() { if (!fs.existsSync(OPENAPI_PATH)) fail(`${OPENAPI_PATH} not found`); const targets = loadPatchTargets(); const lines = fs.readFileSync(OPENAPI_PATH, 'utf8').split('\n'); let changed = false; for (const target of targets) { const updated = patchTarget(lines, target); if (!updated) { console.warn(`patch-openapi: target not found: ${target.method.toUpperCase()} ${target.path}`); } else { changed = true; } } if (changed) { fs.writeFileSync(OPENAPI_PATH, lines.join('\n')); console.log('patch-openapi: updated openapi.yml'); } else { console.log('patch-openapi: no changes applied'); } } main();

Get Started

Essentials

Page Not Found