@wirebench/engine 2.1.1

package/dist/rest/openapi/parse.js

@@ -0,0 +1,1530 @@
+/**
+ * Reading an OpenAPI or Swagger document into the model this client imports from.
+ *
+ * Tolerant on purpose. A description in the wild is written by hand, generated by a framework, or
+ * both, and a parser that refuses a whole document because one operation is malformed refuses
+ * documents users legitimately need. So anything that cannot be understood is *skipped and counted*
+ * — the import summary names it — and only two things are fatal: text that is neither JSON nor
+ * YAML, and a document that does not declare a supported OpenAPI or Swagger version. Swagger 1.x
+ * and 2.0 documents are converted into the intermediate OpenAPI representation.
+ *
+ * The parser reads a document that is already resolved: `refs.ts` inlines every `$ref` first, so
+ * nothing here has to fetch anything.
+ */
+import { parse as parseYamlDocument } from 'yaml';
+import { OpenApiError } from '../../errors.js';
+import { HTTP_METHODS } from './model.js';
+import { trimTrailingSlashes } from '../url.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function asBoolean(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const strings = value.filter((entry) => typeof entry === 'string');
+    // All-or-nothing: a list with a non-string in it is not a list of strings, and silently dropping
+    // the odd one out would misreport what the document said.
+    return strings.length === value.length ? strings : undefined;
+}
+/** A value carried through as it was written — an `example`, a `default`, an `enum` member. */
+function asJson(value) {
+    return value === undefined ? undefined : value;
+}
+/**
+ * Parses text as JSON when it looks like JSON, and as YAML otherwise.
+ *
+ * JSON is a subset of YAML, so one parser would do — but a JSON document with a syntax error gets a
+ * far better message from `JSON.parse`, and that message is what the user has to act on.
+ *
+ * @throws OpenApiError `openapi-malformed` when the text parses as neither.
+ */
+export function parseDocumentText(text, where = 'the document') {
+    const trimmed = text.replace(/^/, '').trimStart();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch (error) {
+            throw new OpenApiError('openapi-malformed', `${where} is not valid JSON: ${messageOf(error)}`, { cause: error });
+        }
+    }
+    try {
+        return parseYamlDocument(trimmed);
+    }
+    catch (error) {
+        throw new OpenApiError('openapi-malformed', `${where} is not valid YAML: ${messageOf(error)}`, { cause: error });
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function asVersionString(v) {
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number') {
+        return Number.isInteger(v) ? `${v}.0` : String(v);
+    }
+    return undefined;
+}
+function nullRecord() {
+    return Object.create(null);
+}
+/**
+ * The version a document declares, as a major-minor this client supports.
+ *
+ * @throws OpenApiError `openapi-unsupported-version` for an OpenAPI major this client
+ * does not read, and `openapi-not-a-document` when there is no version at all.
+ */
+export function versionOf(root) {
+    if (!isRecord(root)) {
+        throw new OpenApiError('openapi-not-a-document', 'This file does not contain an OpenAPI document');
+    }
+    // 3.1: Check openapi BEFORE swagger/swaggerVersion
+    const declared = asVersionString(root['openapi']);
+    if (declared !== undefined) {
+        if (declared.startsWith('3.0')) {
+            return { version: '3.0', declared };
+        }
+        if (declared.startsWith('3.1')) {
+            return { version: '3.1', declared };
+        }
+        if (declared.startsWith('3.2')) {
+            return { version: '3.2', declared };
+        }
+        throw new OpenApiError('openapi-unsupported-version', `OpenAPI ${declared} is not supported. Wirebench imports OpenAPI 3.0, 3.1 and 3.2.`, { details: { declared } });
+    }
+    // 3.2: Accept numeric versions for swagger/swaggerVersion as well
+    const swaggerVersion = asVersionString(root['swaggerVersion']) ?? asVersionString(root['swagger']);
+    if (swaggerVersion !== undefined) {
+        // 3.10: report 1.0/1.1 as exact version, remove redundant === '1.2'
+        if (swaggerVersion.startsWith('1.0')) {
+            return { version: '1.0', declared: `Swagger ${swaggerVersion}` };
+        }
+        if (swaggerVersion.startsWith('1.1')) {
+            return { version: '1.1', declared: `Swagger ${swaggerVersion}` };
+        }
+        if (swaggerVersion.startsWith('1.')) {
+            return { version: '1.2', declared: `Swagger ${swaggerVersion}` };
+        }
+        if (swaggerVersion.startsWith('2.')) {
+            return { version: '2.0', declared: `Swagger ${swaggerVersion}` };
+        }
+        // 3.3: Swagger 3.x is labeled as OpenAPI 3.x.y
+        if (swaggerVersion.startsWith('3.0')) {
+            return { version: '3.0', declared: `OpenAPI ${swaggerVersion}` };
+        }
+        if (swaggerVersion.startsWith('3.1')) {
+            return { version: '3.1', declared: `OpenAPI ${swaggerVersion}` };
+        }
+        if (swaggerVersion.startsWith('3.2')) {
+            return { version: '3.2', declared: `OpenAPI ${swaggerVersion}` };
+        }
+        throw new OpenApiError('openapi-unsupported-version', `This is a Swagger ${swaggerVersion} document. Wirebench imports Swagger 1.x, 2.0, 3.x and OpenAPI 3.0, 3.1, 3.2.`, { details: { declared: swaggerVersion } });
+    }
+    throw new OpenApiError('openapi-not-a-document', 'This file has no "openapi" or "swaggerVersion" field, so it is not an OpenAPI or Swagger document');
+}
+/** The keys a document may carry that this client knowingly does not read, with what to call them. */
+const IGNORED_ROOT_KEYS = {
+    webhooks: 'webhook',
+    callbacks: 'callback',
+    links: 'link',
+};
+/**
+ * Reads a resolved OpenAPI document.
+ *
+ * @param root the parsed document, with every `$ref` already inlined (see `refs.ts`)
+ * @throws OpenApiError `openapi-not-a-document` / `openapi-unsupported-version` as {@link versionOf} does
+ */
+export function parseOpenApiDocument(root) {
+    const { version, declared } = versionOf(root);
+    const document = root;
+    if (version === '1.0' || version === '1.1' || version === '1.2') {
+        return parseSwagger1Document(document, declared, version);
+    }
+    if (version === '2.0') {
+        return parseSwagger2Document(document, declared);
+    }
+    const skipped = [];
+    const rawSwagger = asVersionString(document['swagger']);
+    if (rawSwagger !== undefined &&
+        (rawSwagger.startsWith('3.0') || rawSwagger.startsWith('3.1') || rawSwagger.startsWith('3.2'))) {
+        skipped.push({ kind: 'info', where: '/swagger', reason: `declared as swagger: ${rawSwagger}` });
+    }
+    const info = isRecord(document['info']) ? document['info'] : {};
+    const title = asString(info['title']) ?? 'Imported API';
+    for (const [key, kind] of Object.entries(IGNORED_ROOT_KEYS)) {
+        const value = document[key];
+        if (isRecord(value)) {
+            for (const name of Object.keys(value)) {
+                skipped.push({ kind, where: `/${key}/${name}`, reason: `${kind}s are not imported` });
+            }
+        }
+    }
+    for (const key of Object.keys(document)) {
+        if (key.startsWith('x-')) {
+            skipped.push({ kind: 'extension', where: `/${key}`, reason: 'vendor extensions are not imported' });
+        }
+    }
+    return {
+        version,
+        declaredVersion: declared,
+        info: {
+            title,
+            ...(asString(info['version']) !== undefined ? { version: asString(info['version']) } : {}),
+            ...(asString(info['description']) !== undefined ? { description: asString(info['description']) } : {}),
+        },
+        servers: parseServers(document['servers'], skipped),
+        operations: parseOperations(document['paths'], skipped),
+        securitySchemes: parseSecuritySchemes(document, skipped),
+        ...(parseSecurityRequirements(document['security']) !== undefined
+            ? { security: parseSecurityRequirements(document['security']) }
+            : {}),
+        tags: parseTags(document['tags']),
+        skipped,
+    };
+}
+function parseServers(value, skipped) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const servers = [];
+    value.forEach((entry, index) => {
+        if (!isRecord(entry)) {
+            skipped.push({ kind: 'server', where: `/servers/${String(index)}`, reason: 'not an object' });
+            return;
+        }
+        const url = asString(entry['url']);
+        if (url === undefined) {
+            skipped.push({ kind: 'server', where: `/servers/${String(index)}`, reason: 'no url' });
+            return;
+        }
+        const variables = parseServerVariables(entry['variables']);
+        servers.push({
+            url,
+            ...(asString(entry['description']) !== undefined
+                ? { description: asString(entry['description']) }
+                : {}),
+            ...(variables !== undefined ? { variables } : {}),
+        });
+    });
+    return servers;
+}
+function parseServerVariables(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const variables = {};
+    for (const [name, entry] of Object.entries(value)) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        // A variable with no default has nothing to substitute, so the template survives into the base
+        // URL — see `serverUrl`.
+        const fallback = asString(entry['default']);
+        variables[name] = {
+            ...(fallback !== undefined ? { default: fallback } : {}),
+            ...(asStringArray(entry['enum']) !== undefined ? { enum: asStringArray(entry['enum']) } : {}),
+            ...(asString(entry['description']) !== undefined
+                ? { description: asString(entry['description']) }
+                : {}),
+        };
+    }
+    return Object.keys(variables).length === 0 ? undefined : variables;
+}
+const RFC_9110_METHOD_TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const FIXED_PATH_ITEM_METHODS = new Set(HTTP_METHODS);
+function parseOperations(value, skipped) {
+    if (!isRecord(value)) {
+        return [];
+    }
+    const operations = [];
+    for (const [path, item] of Object.entries(value)) {
+        if (path.startsWith('x-')) {
+            skipped.push({ kind: 'extension', where: `/paths/${path}`, reason: 'vendor extensions are not imported' });
+            continue;
+        }
+        if (!isRecord(item)) {
+            skipped.push({ kind: 'path', where: `/paths/${path}`, reason: 'not a path item' });
+            continue;
+        }
+        const shared = parseParameters(item['parameters'], `${path} (path level)`, skipped);
+        for (const [key, operation] of Object.entries(item)) {
+            if (!HTTP_METHODS.includes(key.toLowerCase())) {
+                continue;
+            }
+            if (!isRecord(operation)) {
+                skipped.push({ kind: 'operation', where: `${key.toUpperCase()} ${path}`, reason: 'not an object' });
+                continue;
+            }
+            operations.push(parseOperation(key.toLowerCase(), path, operation, shared, skipped));
+        }
+        if (isRecord(item['additionalOperations'])) {
+            for (const [key, operation] of Object.entries(item['additionalOperations'])) {
+                if (key.startsWith('x-')) {
+                    skipped.push({ kind: 'extension', where: `${key} ${path}`, reason: 'vendor extensions are not imported' });
+                    continue;
+                }
+                if (FIXED_PATH_ITEM_METHODS.has(key.toLowerCase())) {
+                    skipped.push({ kind: 'operation', where: `${key} ${path}`, reason: 'use the fixed field' });
+                    continue;
+                }
+                if (!RFC_9110_METHOD_TOKEN.test(key)) {
+                    skipped.push({ kind: 'operation', where: `${key} ${path}`, reason: 'invalid HTTP method name' });
+                    continue;
+                }
+                if (!isRecord(operation)) {
+                    skipped.push({ kind: 'operation', where: `${key} ${path}`, reason: 'not an object' });
+                    continue;
+                }
+                operations.push(parseOperation(key, path, operation, shared, skipped));
+            }
+        }
+    }
+    return operations;
+}
+function parseOperation(method, path, operation, shared, skipped) {
+    const where = `${method.toUpperCase()} ${path}`;
+    const own = parseParameters(operation['parameters'], where, skipped);
+    // "The operation's own wins", keyed by name *and* location — the specification's own identity for
+    // a parameter, so a `petId` in the path and a `petId` in the query stay two parameters.
+    const merged = new Map();
+    for (const parameter of [...shared, ...own]) {
+        merged.set(`${parameter.in}:${parameter.name}`, parameter);
+    }
+    for (const key of Object.keys(operation)) {
+        if (key === 'callbacks' || key === 'links') {
+            skipped.push({ kind: key.replace(/s$/, ''), where, reason: `${key} are not imported` });
+        }
+        if (key.startsWith('x-')) {
+            skipped.push({ kind: 'extension', where: `${where} ${key}`, reason: 'vendor extensions are not imported' });
+        }
+    }
+    const requestBody = parseRequestBody(operation['requestBody'], where, skipped);
+    const security = parseSecurityRequirements(operation['security']);
+    return {
+        method,
+        path,
+        parameters: [...merged.values()],
+        ...(asString(operation['operationId']) !== undefined
+            ? { operationId: asString(operation['operationId']) }
+            : {}),
+        ...(asString(operation['summary']) !== undefined ? { summary: asString(operation['summary']) } : {}),
+        ...(asString(operation['description']) !== undefined
+            ? { description: asString(operation['description']) }
+            : {}),
+        ...(asStringArray(operation['tags']) !== undefined ? { tags: asStringArray(operation['tags']) } : {}),
+        ...(asBoolean(operation['deprecated']) === true ? { deprecated: true } : {}),
+        ...(requestBody !== undefined ? { requestBody } : {}),
+        ...(security !== undefined ? { security } : {}),
+    };
+}
+function parseParameters(value, where, skipped) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const parameters = [];
+    value.forEach((entry, index) => {
+        if (!isRecord(entry)) {
+            skipped.push({ kind: 'parameter', where: `${where} #${String(index)}`, reason: 'not an object' });
+            return;
+        }
+        const name = asString(entry['name']);
+        const location = asString(entry['in']);
+        if (name === undefined || location === undefined) {
+            skipped.push({
+                kind: 'parameter',
+                where: `${where} #${String(index)}`,
+                reason: entry['$ref'] !== undefined ? 'its $ref could not be resolved' : 'no name or location',
+            });
+            return;
+        }
+        if (!['path', 'query', 'header', 'cookie'].includes(location)) {
+            skipped.push({ kind: 'parameter', where: `${where} ${name}`, reason: `unknown location "${location}"` });
+            return;
+        }
+        parameters.push({
+            name,
+            in: location,
+            ...(asBoolean(entry['required']) !== undefined ? { required: asBoolean(entry['required']) } : {}),
+            ...(asBoolean(entry['deprecated']) === true ? { deprecated: true } : {}),
+            ...(asString(entry['description']) !== undefined
+                ? { description: asString(entry['description']) }
+                : {}),
+            ...(isRecord(entry['schema']) ? { schema: parseSchema(entry['schema']) } : {}),
+            ...(entry['example'] !== undefined ? { example: asJson(entry['example']) } : {}),
+            ...(parseExamples(entry['examples']) !== undefined
+                ? { examples: parseExamples(entry['examples']) }
+                : {}),
+            ...(asString(entry['style']) !== undefined ? { style: asString(entry['style']) } : {}),
+            ...(asBoolean(entry['explode']) !== undefined ? { explode: asBoolean(entry['explode']) } : {}),
+        });
+    });
+    return parameters;
+}
+function parseExamples(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const examples = nullRecord();
+    for (const [name, entry] of Object.entries(value)) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        const val = asJson(entry['value'] ?? entry['dataValue'] ?? entry['serializedValue']);
+        const dataValue = asJson(entry['dataValue']);
+        const serializedValue = asString(entry['serializedValue']);
+        examples[name] = {
+            ...(val !== undefined ? { value: val } : {}),
+            ...(dataValue !== undefined ? { dataValue } : {}),
+            ...(serializedValue !== undefined ? { serializedValue } : {}),
+            ...(asString(entry['summary']) !== undefined ? { summary: asString(entry['summary']) } : {}),
+            ...(asString(entry['externalValue']) !== undefined
+                ? { externalValue: asString(entry['externalValue']) }
+                : {}),
+        };
+    }
+    return Object.keys(examples).length === 0 ? undefined : examples;
+}
+function parseRequestBody(value, where, skipped) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    if (!isRecord(value['content'])) {
+        skipped.push({
+            kind: 'requestBody',
+            where,
+            reason: value['$ref'] !== undefined ? 'its $ref could not be resolved' : 'no content',
+        });
+        return undefined;
+    }
+    const content = nullRecord();
+    for (const [mediaType, entry] of Object.entries(value['content'])) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        const schema = isRecord(entry['schema'])
+            ? parseSchema(entry['schema'])
+            : isRecord(entry['itemSchema'])
+                ? parseSchema(entry['itemSchema'])
+                : undefined;
+        const itemSchema = isRecord(entry['itemSchema']) ? parseSchema(entry['itemSchema']) : undefined;
+        content[mediaType] = {
+            ...(schema !== undefined ? { schema } : {}),
+            ...(itemSchema !== undefined ? { itemSchema } : {}),
+            ...(entry['example'] !== undefined ? { example: asJson(entry['example']) } : {}),
+            ...(parseExamples(entry['examples']) !== undefined
+                ? { examples: parseExamples(entry['examples']) }
+                : {}),
+        };
+    }
+    return {
+        content,
+        ...(asBoolean(value['required']) !== undefined ? { required: asBoolean(value['required']) } : {}),
+        ...(asString(value['description']) !== undefined ? { description: asString(value['description']) } : {}),
+    };
+}
+/** Reads a schema, keeping only what a sample generator needs. Recursive, and structure-only. */
+/**
+ * One parsed schema per resolved node, keyed by the node itself.
+ *
+ * A `$ref`-resolved description is a *graph*: `refs.ts` hands back one object per reference target,
+ * shared by every place that referenced it. Rebuilding that graph as a tree — which is what a plain
+ * recursive parse does — revisits a shared node once per path to it, so a document whose schemas
+ * reference each other costs `breadth ^ depth`. Keyed on identity because that is exactly the
+ * question being asked: "have I already parsed *this* node?". A `WeakMap` so a parsed document does
+ * not pin the resolved one in memory after the import is over.
+ */
+const parsedSchemas = new WeakMap();
+export function parseSchema(value) {
+    const already = parsedSchemas.get(value);
+    if (already !== undefined) {
+        return already;
+    }
+    // Placed before the recursion so a self-referencing node — one the resolver left cyclic — resolves
+    // to the same object rather than recursing forever. The placeholder is filled in below.
+    const schema = parseSchemaFields(value);
+    parsedSchemas.set(value, schema);
+    return schema;
+}
+/** The body of {@link parseSchema}, without the memo. */
+function parseSchemaFields(value) {
+    let properties;
+    if (isRecord(value['properties'])) {
+        properties = nullRecord();
+        for (const [name, entry] of Object.entries(value['properties'])) {
+            if (isRecord(entry)) {
+                properties[name] = parseSchema(entry);
+            }
+        }
+    }
+    const branches = (key) => {
+        const list = value[key];
+        return Array.isArray(list) ? list.filter(isRecord).map(parseSchema) : undefined;
+    };
+    const type = value['type'];
+    const additional = value['additionalProperties'];
+    return {
+        ...(typeof type === 'string' || asStringArray(type) !== undefined
+            ? { type: type }
+            : {}),
+        ...(asString(value['format']) !== undefined ? { format: asString(value['format']) } : {}),
+        ...(asString(value['title']) !== undefined ? { title: asString(value['title']) } : {}),
+        ...(asString(value['description']) !== undefined ? { description: asString(value['description']) } : {}),
+        ...(value['default'] !== undefined ? { default: asJson(value['default']) } : {}),
+        ...(value['example'] !== undefined ? { example: asJson(value['example']) } : {}),
+        ...(Array.isArray(value['examples']) ? { examples: value['examples'] } : {}),
+        ...(Array.isArray(value['enum']) ? { enum: value['enum'] } : {}),
+        ...(value['const'] !== undefined ? { const: asJson(value['const']) } : {}),
+        ...(properties !== undefined ? { properties } : {}),
+        ...(asStringArray(value['required']) !== undefined
+            ? { required: asStringArray(value['required']) }
+            : {}),
+        ...(isRecord(value['items']) ? { items: parseSchema(value['items']) } : {}),
+        ...(typeof additional === 'boolean'
+            ? { additionalProperties: additional }
+            : isRecord(additional)
+                ? { additionalProperties: parseSchema(additional) }
+                : {}),
+        ...(branches('allOf') !== undefined ? { allOf: branches('allOf') } : {}),
+        ...(branches('oneOf') !== undefined ? { oneOf: branches('oneOf') } : {}),
+        ...(branches('anyOf') !== undefined ? { anyOf: branches('anyOf') } : {}),
+        ...(asBoolean(value['nullable']) !== undefined ? { nullable: asBoolean(value['nullable']) } : {}),
+        ...(asBoolean(value['deprecated']) === true ? { deprecated: true } : {}),
+        ...(asBoolean(value['readOnly']) === true ? { readOnly: true } : {}),
+        ...(asBoolean(value['writeOnly']) === true ? { writeOnly: true } : {}),
+        ...(isRecord(value['xml']) ? { xml: parseXml(value['xml']) } : {}),
+        // A `$ref` that survived resolution could not be resolved; the sample generator says so rather
+        // than inventing a value for a schema it never saw.
+        ...(asString(value['$ref']) !== undefined ? { $ref: asString(value['$ref']) } : {}),
+    };
+}
+function parseXml(value) {
+    return {
+        ...(asString(value['name']) !== undefined ? { name: asString(value['name']) } : {}),
+        ...(asString(value['namespace']) !== undefined ? { namespace: asString(value['namespace']) } : {}),
+        ...(asString(value['prefix']) !== undefined ? { prefix: asString(value['prefix']) } : {}),
+        ...(asBoolean(value['attribute']) !== undefined ? { attribute: asBoolean(value['attribute']) } : {}),
+        ...(asBoolean(value['wrapped']) !== undefined ? { wrapped: asBoolean(value['wrapped']) } : {}),
+    };
+}
+function parseSecuritySchemes(document, skipped) {
+    const components = document['components'];
+    const schemes = isRecord(components) ? components['securitySchemes'] : undefined;
+    if (!isRecord(schemes)) {
+        return [];
+    }
+    const parsed = [];
+    for (const [name, entry] of Object.entries(schemes)) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        const type = asString(entry['type']);
+        if (type === undefined) {
+            skipped.push({ kind: 'securityScheme', where: `/components/securitySchemes/${name}`, reason: 'no type' });
+            continue;
+        }
+        if (!['http', 'apiKey', 'oauth2', 'openIdConnect', 'mutualTLS'].includes(type)) {
+            skipped.push({
+                kind: 'securityScheme',
+                where: `/components/securitySchemes/${name}`,
+                reason: `unknown type "${type}"`,
+            });
+            continue;
+        }
+        parsed.push({
+            name,
+            type: type,
+            ...(asString(entry['description']) !== undefined
+                ? { description: asString(entry['description']) }
+                : {}),
+            ...(asString(entry['scheme']) !== undefined
+                ? { scheme: asString(entry['scheme']).toLowerCase() }
+                : {}),
+            ...(asString(entry['bearerFormat']) !== undefined
+                ? { bearerFormat: asString(entry['bearerFormat']) }
+                : {}),
+            ...(asString(entry['in']) !== undefined ? { in: asString(entry['in']) } : {}),
+            // `name` on an apiKey scheme is the *parameter's* name, which would collide with the scheme's
+            // own key, so the model calls it `keyName`.
+            ...(asString(entry['name']) !== undefined ? { keyName: asString(entry['name']) } : {}),
+            ...(parseFlows(entry['flows']) !== undefined
+                ? { flows: parseFlows(entry['flows']) }
+                : {}),
+        });
+    }
+    return parsed;
+}
+function parseFlows(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const flows = nullRecord();
+    for (const [name, entry] of Object.entries(value)) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        let scopes;
+        if (isRecord(entry['scopes'])) {
+            const scopesRecord = nullRecord();
+            for (const [scope, description] of Object.entries(entry['scopes'])) {
+                scopesRecord[scope] = asString(description) ?? '';
+            }
+            scopes = scopesRecord;
+        }
+        flows[name] = {
+            ...(asString(entry['authorizationUrl']) !== undefined
+                ? { authorizationUrl: asString(entry['authorizationUrl']) }
+                : {}),
+            ...(asString(entry['tokenUrl']) !== undefined ? { tokenUrl: asString(entry['tokenUrl']) } : {}),
+            ...(asString(entry['refreshUrl']) !== undefined ? { refreshUrl: asString(entry['refreshUrl']) } : {}),
+            ...(scopes !== undefined ? { scopes } : {}),
+        };
+    }
+    return Object.keys(flows).length === 0 ? undefined : flows;
+}
+/**
+ * Security requirements, or `undefined` when the document or operation declares none.
+ *
+ * An empty array is kept as an empty array: `security: []` on an operation means "this one is
+ * explicitly unauthenticated", which is different from saying nothing at all.
+ */
+function parseSecurityRequirements(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    return value.filter(isRecord).map((entry) => {
+        const req = nullRecord();
+        for (const [name, scopes] of Object.entries(entry)) {
+            req[name] = asStringArray(scopes) ?? [];
+        }
+        return req;
+    });
+}
+function parseTags(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const tags = [];
+    for (const entry of value) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        const name = asString(entry['name']);
+        if (name === undefined) {
+            continue;
+        }
+        tags.push({
+            name,
+            ...(asString(entry['description']) !== undefined
+                ? { description: asString(entry['description']) }
+                : {}),
+        });
+    }
+    return tags;
+}
+/**
+ * Reads a resolved Swagger 2.0 document into the internal OpenApiDocument representation.
+ */
+function parseSwagger2Document(document, declared) {
+    const skipped = [];
+    const info = isRecord(document['info']) ? document['info'] : {};
+    const title = asString(info['title']) ?? 'Imported API';
+    for (const key of Object.keys(document)) {
+        if (key.startsWith('x-')) {
+            skipped.push({ kind: 'extension', where: `/${key}`, reason: 'vendor extensions are not imported' });
+        }
+    }
+    if (document['produces'] !== undefined) {
+        skipped.push({ kind: 'produces', where: '/produces', reason: 'produces are not imported' });
+    }
+    if (document['responses'] !== undefined) {
+        skipped.push({ kind: 'responses', where: '/responses', reason: 'responses are not imported' });
+    }
+    return {
+        version: '2.0',
+        declaredVersion: declared,
+        info: {
+            title,
+            ...(asString(info['version']) !== undefined ? { version: asString(info['version']) } : {}),
+            ...(asString(info['description']) !== undefined ? { description: asString(info['description']) } : {}),
+        },
+        servers: parseSwagger2Servers(document),
+        operations: parseSwagger2Operations(document, skipped),
+        securitySchemes: parseSwagger2SecuritySchemes(document['securityDefinitions'], skipped),
+        ...(parseSecurityRequirements(document['security']) !== undefined
+            ? { security: parseSecurityRequirements(document['security']) }
+            : {}),
+        tags: parseTags(document['tags']),
+        skipped,
+    };
+}
+function parseSwagger2Servers(document) {
+    const host = asString(document['host']);
+    let basePath = asString(document['basePath']);
+    if (basePath !== undefined && basePath !== '') {
+        if (!basePath.startsWith('/')) {
+            basePath = `/${basePath}`;
+        }
+    }
+    else {
+        basePath = '';
+    }
+    const rawSchemes = asStringArray(document['schemes']);
+    const validSchemes = (rawSchemes?.filter((s) => s.toLowerCase() === 'http' || s.toLowerCase() === 'https') ?? []).map((s) => s.toLowerCase());
+    if (host !== undefined && host !== '') {
+        const schemeMatch = host.match(/^([a-z][a-z0-9+.-]*):\/\/(.*)$/i);
+        let effectiveHost = host;
+        let schemeFromHost;
+        if (schemeMatch) {
+            schemeFromHost = schemeMatch[1]?.toLowerCase();
+            effectiveHost = schemeMatch[2] ?? '';
+        }
+        const cleanHost = trimTrailingSlashes(effectiveHost);
+        let schemes;
+        if (schemeFromHost) {
+            schemes = [schemeFromHost, ...validSchemes.filter((s) => s !== schemeFromHost)];
+        }
+        else if (validSchemes.length > 0) {
+            schemes = validSchemes;
+        }
+        else {
+            schemes = ['https'];
+        }
+        return schemes.map((scheme) => ({
+            url: `${scheme}://${cleanHost}${basePath}`,
+        }));
+    }
+    if (basePath !== '' && basePath !== '/') {
+        return [{ url: basePath }];
+    }
+    return [{ url: '/' }];
+}
+function parseSwagger2SecuritySchemes(definitions, skipped) {
+    if (!isRecord(definitions)) {
+        return [];
+    }
+    const parsed = [];
+    for (const [name, entry] of Object.entries(definitions)) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        const type = asString(entry['type']);
+        if (type === undefined) {
+            skipped.push({ kind: 'securityScheme', where: `/securityDefinitions/${name}`, reason: 'no type' });
+            continue;
+        }
+        const description = asString(entry['description']);
+        if (type === 'basic') {
+            parsed.push({
+                name,
+                type: 'http',
+                scheme: 'basic',
+                ...(description !== undefined ? { description } : {}),
+            });
+            continue;
+        }
+        if (type === 'apiKey') {
+            const inLoc = asString(entry['in']);
+            const keyName = asString(entry['name']);
+            if (inLoc !== 'header' && inLoc !== 'query') {
+                skipped.push({
+                    kind: 'securityScheme',
+                    where: `/securityDefinitions/${name}`,
+                    reason: `unsupported apiKey location "${inLoc ?? ''}"`,
+                });
+                continue;
+            }
+            parsed.push({
+                name,
+                type: 'apiKey',
+                in: inLoc,
+                keyName: keyName ?? name,
+                ...(description !== undefined ? { description } : {}),
+            });
+            continue;
+        }
+        if (type === 'oauth2') {
+            const rawFlow = asString(entry['flow']);
+            const authorizationUrl = asString(entry['authorizationUrl']);
+            const tokenUrl = asString(entry['tokenUrl']);
+            let scopes;
+            if (isRecord(entry['scopes'])) {
+                const scopesRecord = nullRecord();
+                for (const [scope, desc] of Object.entries(entry['scopes'])) {
+                    scopesRecord[scope] = asString(desc) ?? '';
+                }
+                scopes = scopesRecord;
+            }
+            const flowObj = {
+                ...(authorizationUrl !== undefined ? { authorizationUrl } : {}),
+                ...(tokenUrl !== undefined ? { tokenUrl } : {}),
+                ...(scopes !== undefined ? { scopes } : {}),
+            };
+            let flowName;
+            if (rawFlow === 'implicit') {
+                flowName = 'implicit';
+            }
+            else if (rawFlow === 'password') {
+                flowName = 'password';
+            }
+            else if (rawFlow === 'application') {
+                flowName = 'clientCredentials';
+            }
+            else if (rawFlow === 'accessCode') {
+                flowName = 'authorizationCode';
+            }
+            else {
+                flowName = rawFlow ?? 'implicit';
+            }
+            parsed.push({
+                name,
+                type: 'oauth2',
+                flows: { [flowName]: flowObj },
+                ...(description !== undefined ? { description } : {}),
+            });
+            continue;
+        }
+        skipped.push({
+            kind: 'securityScheme',
+            where: `/securityDefinitions/${name}`,
+            reason: `unknown type "${type}"`,
+        });
+    }
+    return parsed;
+}
+function synthesizeSwagger2ParamSchema(param) {
+    const type = asString(param['type']);
+    const format = asString(param['format']);
+    const items = isRecord(param['items']) ? synthesizeSwagger2ParamSchema(param['items']) : undefined;
+    const enumVals = Array.isArray(param['enum']) ? param['enum'] : undefined;
+    const defaultVal = asJson(param['default']);
+    return {
+        ...(type !== undefined ? { type } : {}),
+        ...(format !== undefined ? { format } : {}),
+        ...(items !== undefined ? { items } : {}),
+        ...(enumVals !== undefined ? { enum: enumVals } : {}),
+        ...(defaultVal !== undefined ? { default: defaultVal } : {}),
+    };
+}
+function swagger2CollectionFormatToStyle(collectionFormat) {
+    if (collectionFormat === 'multi') {
+        return { style: 'form', explode: true };
+    }
+    if (collectionFormat === 'ssv') {
+        return { style: 'spaceDelimited', explode: false };
+    }
+    if (collectionFormat === 'pipes') {
+        return { style: 'pipeDelimited', explode: false };
+    }
+    if (collectionFormat === 'csv') {
+        return { style: 'form', explode: false };
+    }
+    return {};
+}
+function parseSwagger2Operations(document, skipped) {
+    const paths = document['paths'];
+    if (!isRecord(paths)) {
+        return [];
+    }
+    const rootConsumes = asStringArray(document['consumes']);
+    const operations = [];
+    for (const [path, item] of Object.entries(paths)) {
+        if (path.startsWith('x-')) {
+            skipped.push({ kind: 'extension', where: `/paths/${path}`, reason: 'vendor extensions are not imported' });
+            continue;
+        }
+        if (!isRecord(item)) {
+            skipped.push({ kind: 'path', where: `/paths/${path}`, reason: 'not a path item' });
+            continue;
+        }
+        const sharedRaw = Array.isArray(item['parameters']) ? item['parameters'].filter(isRecord) : [];
+        for (const [key, operation] of Object.entries(item)) {
+            if (!HTTP_METHODS.includes(key.toLowerCase())) {
+                continue;
+            }
+            if (!isRecord(operation)) {
+                skipped.push({ kind: 'operation', where: `${key.toUpperCase()} ${path}`, reason: 'not an object' });
+                continue;
+            }
+            const where = `${key.toUpperCase()} ${path}`;
+            const ownRaw = Array.isArray(operation['parameters']) ? operation['parameters'].filter(isRecord) : [];
+            const paramMap = new Map();
+            for (const p of sharedRaw) {
+                const name = asString(p['name']);
+                const location = asString(p['in']);
+                if (name !== undefined && location !== undefined) {
+                    paramMap.set(`${location}:${name}`, p);
+                }
+            }
+            for (const p of ownRaw) {
+                const name = asString(p['name']);
+                const location = asString(p['in']);
+                if (name !== undefined && location !== undefined) {
+                    paramMap.set(`${location}:${name}`, p);
+                }
+            }
+            const allParams = [...paramMap.values()];
+            let bodyParam;
+            const formDataParams = [];
+            const standardParams = [];
+            for (const p of allParams) {
+                const name = asString(p['name']);
+                const location = asString(p['in']);
+                if (name === undefined || location === undefined) {
+                    skipped.push({
+                        kind: 'parameter',
+                        where,
+                        reason: p['$ref'] !== undefined ? 'its $ref could not be resolved' : 'no name or location',
+                    });
+                    continue;
+                }
+                if (location === 'body') {
+                    bodyParam = p;
+                    continue;
+                }
+                if (location === 'formData') {
+                    formDataParams.push(p);
+                    continue;
+                }
+                if (!['path', 'query', 'header'].includes(location)) {
+                    skipped.push({ kind: 'parameter', where: `${where} ${name}`, reason: `unknown location "${location}"` });
+                    continue;
+                }
+                const collectionFormat = asString(p['collectionFormat']);
+                if (collectionFormat === 'tsv') {
+                    skipped.push({
+                        kind: 'parameter',
+                        where: `${where} ${name}`,
+                        reason: 'collectionFormat: tsv is not supported',
+                    });
+                    continue;
+                }
+                const formatStyle = swagger2CollectionFormatToStyle(collectionFormat);
+                const isPath = location === 'path';
+                standardParams.push({
+                    name,
+                    in: location,
+                    ...(isPath
+                        ? { required: true }
+                        : asBoolean(p['required']) !== undefined
+                            ? { required: asBoolean(p['required']) }
+                            : {}),
+                    ...(asBoolean(p['deprecated']) === true ? { deprecated: true } : {}),
+                    ...(asString(p['description']) !== undefined ? { description: asString(p['description']) } : {}),
+                    schema: synthesizeSwagger2ParamSchema(p),
+                    ...(p['default'] !== undefined ? { example: asJson(p['default']) } : {}),
+                    ...(formatStyle.style !== undefined ? { style: formatStyle.style } : {}),
+                    ...(formatStyle.explode !== undefined ? { explode: formatStyle.explode } : {}),
+                });
+            }
+            let requestBody;
+            const opConsumes = asStringArray(operation['consumes']);
+            const effectiveConsumes = opConsumes ?? rootConsumes ?? ['application/json'];
+            const normalizeMediaType = (mt) => mt.split(';')[0]?.trim().toLowerCase() ?? '';
+            if (bodyParam !== undefined) {
+                if (formDataParams.length > 0) {
+                    skipped.push({
+                        kind: 'parameter',
+                        where,
+                        reason: 'formData ignored because operation already has a body parameter',
+                    });
+                }
+                const schema = isRecord(bodyParam['schema']) ? parseSchema(bodyParam['schema']) : undefined;
+                const content = nullRecord();
+                for (const mt of effectiveConsumes) {
+                    content[mt] = {
+                        ...(schema !== undefined ? { schema } : {}),
+                    };
+                }
+                requestBody = {
+                    content,
+                    ...(asBoolean(bodyParam['required']) !== undefined
+                        ? { required: asBoolean(bodyParam['required']) }
+                        : {}),
+                    ...(asString(bodyParam['description']) !== undefined
+                        ? { description: asString(bodyParam['description']) }
+                        : {}),
+                };
+            }
+            else if (formDataParams.length > 0) {
+                const hasFile = formDataParams.some((p) => asString(p['type']) === 'file');
+                const defaultMt = hasFile ? 'multipart/form-data' : 'application/x-www-form-urlencoded';
+                const matchedConsumes = effectiveConsumes.filter((mt) => {
+                    const norm = normalizeMediaType(mt);
+                    return norm === 'multipart/form-data' || norm === 'application/x-www-form-urlencoded';
+                });
+                const formMediaTypes = matchedConsumes.length > 0 ? matchedConsumes : [defaultMt];
+                const properties = nullRecord();
+                const required = [];
+                for (const p of formDataParams) {
+                    const name = asString(p['name']);
+                    if (!name)
+                        continue;
+                    if (asBoolean(p['required']) === true) {
+                        required.push(name);
+                    }
+                    if (asString(p['type']) === 'file') {
+                        properties[name] = {
+                            type: 'string',
+                            format: 'binary',
+                            ...(asString(p['description']) !== undefined
+                                ? { description: asString(p['description']) }
+                                : {}),
+                        };
+                    }
+                    else {
+                        properties[name] = synthesizeSwagger2ParamSchema(p);
+                    }
+                }
+                const schema = {
+                    type: 'object',
+                    properties,
+                    ...(required.length > 0 ? { required } : {}),
+                };
+                const content = nullRecord();
+                for (const mt of formMediaTypes) {
+                    content[mt] = { schema };
+                }
+                requestBody = {
+                    content,
+                    required: required.length > 0,
+                };
+            }
+            for (const opKey of Object.keys(operation)) {
+                if (opKey.startsWith('x-')) {
+                    if (opKey === 'x-example') {
+                        skipped.push({ kind: 'example', where: `${where} x-example`, reason: 'examples are not imported' });
+                    }
+                    else {
+                        skipped.push({
+                            kind: 'extension',
+                            where: `${where} ${opKey}`,
+                            reason: 'vendor extensions are not imported',
+                        });
+                    }
+                }
+                else if (opKey === 'produces') {
+                    skipped.push({ kind: 'produces', where: `${where} produces`, reason: 'produces are not imported' });
+                }
+                else if (opKey === 'responses') {
+                    skipped.push({ kind: 'responses', where: `${where} responses`, reason: 'responses are not imported' });
+                }
+                else if (opKey === 'example') {
+                    skipped.push({ kind: 'example', where: `${where} example`, reason: 'examples are not imported' });
+                }
+            }
+            const security = parseSecurityRequirements(operation['security']);
+            operations.push({
+                method: key.toLowerCase(),
+                path,
+                parameters: standardParams,
+                ...(asString(operation['operationId']) !== undefined
+                    ? { operationId: asString(operation['operationId']) }
+                    : {}),
+                ...(asString(operation['summary']) !== undefined ? { summary: asString(operation['summary']) } : {}),
+                ...(asString(operation['description']) !== undefined
+                    ? { description: asString(operation['description']) }
+                    : {}),
+                ...(asStringArray(operation['tags']) !== undefined
+                    ? { tags: asStringArray(operation['tags']) }
+                    : {}),
+                ...(asBoolean(operation['deprecated']) === true ? { deprecated: true } : {}),
+                ...(requestBody !== undefined ? { requestBody } : {}),
+                ...(security !== undefined ? { security } : {}),
+            });
+        }
+    }
+    return operations;
+}
+/**
+ * Reads a Swagger 1.0, 1.1, or 1.2 document (API Declaration or Resource Listing) into the internal
+ * OpenApiDocument representation.
+ */
+function parseSwagger1Document(document, declared, version = '1.2') {
+    const skipped = [];
+    const info = isRecord(document['info']) ? document['info'] : {};
+    const resourcePath = asString(document['resourcePath']);
+    const title = asString(info['title']) ??
+        (resourcePath !== undefined && resourcePath.length > 1 ? resourcePath.replace(/^\//, '') : 'Imported API');
+    for (const key of Object.keys(document)) {
+        if (key.startsWith('x-')) {
+            skipped.push({ kind: 'extension', where: `/${key}`, reason: 'vendor extensions are not imported' });
+        }
+    }
+    const modelCtx = {
+        rawModels: isRecord(document['models']) ? document['models'] : {},
+        memo: new Map(),
+    };
+    const servers = parseSwagger1Servers(document);
+    const operations = parseSwagger1Operations(document, modelCtx, skipped);
+    if (operations.length === 0 && Array.isArray(document['apis']) && document['apis'].length > 0) {
+        throw new OpenApiError('openapi-resource-listing-not-inlined', 'Swagger 1.2 Resource Listing contains external API declarations that are not inlined and yielded no operations');
+    }
+    const securitySchemes = parseSwagger1SecuritySchemes(document['authorizations'], skipped);
+    const tags = parseSwagger1Tags(document);
+    return {
+        version,
+        declaredVersion: declared,
+        info: {
+            title,
+            ...(asString(document['apiVersion']) !== undefined
+                ? { version: asString(document['apiVersion']) }
+                : asString(info['version']) !== undefined
+                    ? { version: asString(info['version']) }
+                    : {}),
+            ...(asString(info['description']) !== undefined ? { description: asString(info['description']) } : {}),
+        },
+        servers,
+        operations,
+        securitySchemes,
+        tags,
+        skipped,
+    };
+}
+function parseSwagger1Servers(document) {
+    const basePath = asString(document['basePath']);
+    if (basePath !== undefined && basePath.trim().length > 0) {
+        return [{ url: basePath.trim() }];
+    }
+    return [{ url: '/' }];
+}
+function parseSwagger1Tags(document) {
+    const tags = [];
+    const resourcePath = asString(document['resourcePath']);
+    if (resourcePath !== undefined && resourcePath.length > 1) {
+        const tagName = resourcePath.replace(/^\//, '');
+        const info = isRecord(document['info']) ? document['info'] : {};
+        tags.push({
+            name: tagName,
+            ...(asString(info['description']) !== undefined ? { description: asString(info['description']) } : {}),
+        });
+    }
+    return tags;
+}
+function normalizeSwagger1Type(rawType) {
+    if (rawType === undefined) {
+        return {};
+    }
+    const lower = rawType.toLowerCase();
+    switch (lower) {
+        case 'string':
+            return { type: 'string' };
+        case 'integer':
+        case 'int':
+        case 'int32':
+            return { type: 'integer', format: 'int32' };
+        case 'long':
+        case 'int64':
+            return { type: 'integer', format: 'int64' };
+        case 'float':
+            return { type: 'number', format: 'float' };
+        case 'double':
+            return { type: 'number', format: 'double' };
+        case 'number':
+            return { type: 'number' };
+        case 'boolean':
+        case 'bool':
+            return { type: 'boolean' };
+        case 'byte':
+            return { type: 'string', format: 'byte' };
+        case 'date':
+            return { type: 'string', format: 'date' };
+        case 'date-time':
+        case 'datetime':
+            return { type: 'string', format: 'date-time' };
+        case 'file':
+            return { type: 'string', format: 'binary' };
+        case 'array':
+        case 'list':
+        case 'set':
+            return { type: 'array' };
+        case 'void':
+            return {};
+        default:
+            // An unknown type name (typically an undeclared model) is not a JSON Schema type.
+            return {};
+    }
+}
+function resolveSwagger1Model(name, ctx, visiting = new Set()) {
+    if (visiting.has(name)) {
+        return { type: 'object', properties: {} };
+    }
+    const cached = ctx.memo.get(name);
+    if (cached !== undefined) {
+        return cached;
+    }
+    if (!Object.hasOwn(ctx.rawModels, name)) {
+        return { type: 'object' };
+    }
+    visiting.add(name);
+    const raw = ctx.rawModels[name];
+    if (!raw) {
+        visiting.delete(name);
+        return { type: 'object' };
+    }
+    const required = asStringArray(raw['required']);
+    const propertiesRaw = isRecord(raw['properties']) ? raw['properties'] : {};
+    const properties = nullRecord();
+    for (const [propName, propVal] of Object.entries(propertiesRaw)) {
+        if (!isRecord(propVal))
+            continue;
+        properties[propName] = convertSwagger1Property(propVal, ctx, new Set(visiting));
+    }
+    const schema = {
+        type: 'object',
+        ...(asString(raw['description']) !== undefined ? { description: asString(raw['description']) } : {}),
+        ...(required && required.length > 0 ? { required } : {}),
+        properties,
+    };
+    visiting.delete(name);
+    ctx.memo.set(name, schema);
+    return schema;
+}
+function convertSwagger1Property(prop, ctx, visiting) {
+    const ref = asString(prop['$ref']);
+    const rawType = asString(prop['type']) ?? asString(prop['dataType']);
+    const format = asString(prop['format']);
+    const description = asString(prop['description']);
+    const enumVals = Array.isArray(prop['enum']) ? prop['enum'] : undefined;
+    const defaultVal = asJson(prop['defaultValue'] ?? prop['default']);
+    const hasRef = ref !== undefined && Object.hasOwn(ctx.rawModels, ref);
+    const hasRawType = rawType !== undefined && Object.hasOwn(ctx.rawModels, rawType);
+    const modelRefName = hasRef ? ref : hasRawType ? rawType : undefined;
+    if (modelRefName !== undefined) {
+        return {
+            ...resolveSwagger1Model(modelRefName, ctx, visiting),
+            ...(description !== undefined ? { description } : {}),
+        };
+    }
+    const normalized = normalizeSwagger1Type(rawType);
+    if (normalized.type === 'array') {
+        let itemsSchema;
+        const items = isRecord(prop['items']) ? prop['items'] : undefined;
+        if (items !== undefined) {
+            itemsSchema = convertSwagger1Property(items, ctx, visiting);
+        }
+        else {
+            itemsSchema = { type: 'string' };
+        }
+        return {
+            type: 'array',
+            items: itemsSchema,
+            ...(description !== undefined ? { description } : {}),
+        };
+    }
+    return {
+        type: normalized.type ?? 'string',
+        ...(format !== undefined ? { format } : normalized.format !== undefined ? { format: normalized.format } : {}),
+        ...(description !== undefined ? { description } : {}),
+        ...(enumVals !== undefined && enumVals.length > 0 ? { enum: enumVals } : {}),
+        ...(defaultVal !== undefined ? { default: defaultVal } : {}),
+    };
+}
+function synthesizeSwagger1ParamPrimitiveSchema(param) {
+    const rawType = asString(param['type']) ?? asString(param['dataType']);
+    const normalized = normalizeSwagger1Type(rawType);
+    const format = asString(param['format']) ?? normalized.format;
+    const enumVals = Array.isArray(param['enum']) ? param['enum'] : undefined;
+    const defaultVal = asJson(param['defaultValue'] ?? param['default']);
+    return {
+        type: normalized.type ?? 'string',
+        ...(format !== undefined ? { format } : {}),
+        ...(enumVals !== undefined && enumVals.length > 0 ? { enum: enumVals } : {}),
+        ...(defaultVal !== undefined ? { default: defaultVal } : {}),
+    };
+}
+function parseSwagger1Operations(document, modelCtx, skipped) {
+    const rawApis = document['apis'];
+    if (!Array.isArray(rawApis)) {
+        return [];
+    }
+    const rootConsumes = asStringArray(document['consumes']);
+    const resourcePath = asString(document['resourcePath']);
+    const operations = [];
+    for (const apiItem of rawApis) {
+        if (!isRecord(apiItem)) {
+            continue;
+        }
+        const path = asString(apiItem['path']);
+        if (path === undefined) {
+            continue;
+        }
+        const rawOperations = apiItem['operations'];
+        if (!Array.isArray(rawOperations)) {
+            skipped.push({
+                kind: 'resource',
+                where: path,
+                reason: 'Resource Listing references sub-resource file that is not inlined',
+            });
+            continue;
+        }
+        for (const op of rawOperations) {
+            if (!isRecord(op)) {
+                continue;
+            }
+            const rawMethod = asString(op['method']) ?? asString(op['httpMethod']);
+            if (rawMethod === undefined || !HTTP_METHODS.includes(rawMethod.toLowerCase())) {
+                continue;
+            }
+            const method = rawMethod.toLowerCase();
+            const where = `${method.toUpperCase()} ${path}`;
+            const rawParams = Array.isArray(op['parameters']) ? op['parameters'].filter(isRecord) : [];
+            let bodyParam;
+            const formDataParams = [];
+            const standardParams = [];
+            for (const p of rawParams) {
+                const name = asString(p['name']);
+                const paramType = asString(p['paramType']);
+                if (name === undefined || paramType === undefined) {
+                    skipped.push({ kind: 'parameter', where, reason: 'parameter without name or paramType' });
+                    continue;
+                }
+                if (paramType === 'body') {
+                    bodyParam = p;
+                    continue;
+                }
+                if (paramType === 'form') {
+                    formDataParams.push(p);
+                    continue;
+                }
+                if (!['path', 'query', 'header'].includes(paramType)) {
+                    skipped.push({ kind: 'parameter', where: `${where} ${name}`, reason: `unknown location "${paramType}"` });
+                    continue;
+                }
+                const allowMultiple = asBoolean(p['allowMultiple']) === true;
+                let schema;
+                if (allowMultiple) {
+                    schema = { type: 'array', items: synthesizeSwagger1ParamPrimitiveSchema(p) };
+                }
+                else {
+                    schema = synthesizeSwagger1ParamPrimitiveSchema(p);
+                }
+                standardParams.push({
+                    name,
+                    in: paramType,
+                    ...(paramType === 'path'
+                        ? { required: true }
+                        : asBoolean(p['required']) !== undefined
+                            ? { required: asBoolean(p['required']) }
+                            : {}),
+                    ...(asString(p['description']) !== undefined ? { description: asString(p['description']) } : {}),
+                    schema,
+                    ...(p['defaultValue'] !== undefined || p['default'] !== undefined
+                        ? { example: asJson(p['defaultValue'] ?? p['default']) }
+                        : {}),
+                });
+            }
+            let requestBody;
+            const opConsumes = asStringArray(op['consumes']);
+            const effectiveConsumes = opConsumes ?? rootConsumes ?? ['application/json'];
+            if (bodyParam !== undefined) {
+                const bodyType = asString(bodyParam['type']) ?? asString(bodyParam['dataType']);
+                let bodySchema;
+                if (bodyType !== undefined && Object.hasOwn(modelCtx.rawModels, bodyType)) {
+                    bodySchema = resolveSwagger1Model(bodyType, modelCtx);
+                }
+                else if (bodyType !== undefined) {
+                    bodySchema = synthesizeSwagger1ParamPrimitiveSchema(bodyParam);
+                }
+                const content = nullRecord();
+                for (const mt of effectiveConsumes) {
+                    content[mt] = {
+                        ...(bodySchema !== undefined ? { schema: bodySchema } : {}),
+                    };
+                }
+                requestBody = {
+                    content,
+                    ...(asBoolean(bodyParam['required']) !== undefined
+                        ? { required: asBoolean(bodyParam['required']) }
+                        : {}),
+                    ...(asString(bodyParam['description']) !== undefined
+                        ? { description: asString(bodyParam['description']) }
+                        : {}),
+                };
+            }
+            else if (formDataParams.length > 0) {
+                const properties = nullRecord();
+                const required = [];
+                let hasFile = false;
+                for (const p of formDataParams) {
+                    const pName = asString(p['name']) ?? 'field';
+                    const pType = asString(p['type']) ?? asString(p['dataType']);
+                    if (pType?.toLowerCase() === 'file') {
+                        hasFile = true;
+                        properties[pName] = { type: 'string', format: 'binary' };
+                    }
+                    else {
+                        properties[pName] = synthesizeSwagger1ParamPrimitiveSchema(p);
+                    }
+                    if (asBoolean(p['required']) === true) {
+                        required.push(pName);
+                    }
+                }
+                const contentType = hasFile ? 'multipart/form-data' : 'application/x-www-form-urlencoded';
+                requestBody = {
+                    content: {
+                        [contentType]: {
+                            schema: {
+                                type: 'object',
+                                properties,
+                                ...(required.length > 0 ? { required } : {}),
+                            },
+                        },
+                    },
+                };
+            }
+            // Security requirements
+            const security = [];
+            if (isRecord(op['authorizations'])) {
+                const req = nullRecord();
+                for (const [schemeName, scopesRaw] of Object.entries(op['authorizations'])) {
+                    const scopes = [];
+                    if (Array.isArray(scopesRaw)) {
+                        for (const scopeItem of scopesRaw) {
+                            if (isRecord(scopeItem) && typeof scopeItem['scope'] === 'string') {
+                                scopes.push(scopeItem['scope']);
+                            }
+                            else if (typeof scopeItem === 'string') {
+                                scopes.push(scopeItem);
+                            }
+                        }
+                    }
+                    req[schemeName] = scopes;
+                }
+                if (Object.keys(req).length > 0) {
+                    security.push(req);
+                }
+            }
+            // Tag derivation
+            let tag;
+            if (resourcePath !== undefined && resourcePath.length > 1) {
+                tag = resourcePath.replace(/^\//, '');
+            }
+            else {
+                const segs = path.split('/').filter((s) => s.length > 0 && !s.startsWith('{'));
+                if (segs.length > 0) {
+                    tag = segs[0];
+                }
+            }
+            const tags = tag !== undefined ? [tag] : undefined;
+            const isDeprecated = op['deprecated'] === true || op['deprecated'] === 'true';
+            operations.push({
+                method,
+                path,
+                parameters: standardParams,
+                ...(asString(op['nickname']) !== undefined ? { operationId: asString(op['nickname']) } : {}),
+                ...(asString(op['summary']) !== undefined ? { summary: asString(op['summary']) } : {}),
+                ...(asString(op['notes']) !== undefined
+                    ? { description: asString(op['notes']) }
+                    : asString(op['description']) !== undefined
+                        ? { description: asString(op['description']) }
+                        : {}),
+                ...(tags !== undefined ? { tags } : {}),
+                ...(isDeprecated ? { deprecated: true } : {}),
+                ...(requestBody !== undefined ? { requestBody } : {}),
+                ...(security.length > 0 ? { security } : {}),
+            });
+        }
+    }
+    return operations;
+}
+function parseSwagger1SecuritySchemes(authorizations, skipped) {
+    if (!isRecord(authorizations)) {
+        return [];
+    }
+    const parsed = [];
+    for (const [name, entry] of Object.entries(authorizations)) {
+        if (!isRecord(entry))
+            continue;
+        const type = asString(entry['type']);
+        if (type === undefined) {
+            skipped.push({ kind: 'securityScheme', where: `/authorizations/${name}`, reason: 'no type' });
+            continue;
+        }
+        const description = asString(entry['description']);
+        if (type === 'basicAuth' || type === 'basic') {
+            parsed.push({
+                name,
+                type: 'http',
+                scheme: 'basic',
+                ...(description !== undefined ? { description } : {}),
+            });
+            continue;
+        }
+        if (type === 'apiKey') {
+            const passAs = asString(entry['passAs']) ?? asString(entry['in']);
+            const keyname = asString(entry['keyname']) ?? asString(entry['name']);
+            if (passAs !== 'header' && passAs !== 'query') {
+                skipped.push({
+                    kind: 'securityScheme',
+                    where: `/authorizations/${name}`,
+                    reason: `unsupported apiKey location "${passAs ?? ''}"`,
+                });
+                continue;
+            }
+            parsed.push({
+                name,
+                type: 'apiKey',
+                in: passAs,
+                keyName: keyname ?? name,
+                ...(description !== undefined ? { description } : {}),
+            });
+            continue;
+        }
+        if (type === 'oauth2') {
+            const scopesMap = nullRecord();
+            if (Array.isArray(entry['scopes'])) {
+                for (const s of entry['scopes']) {
+                    if (isRecord(s) && typeof s['scope'] === 'string') {
+                        scopesMap[s['scope']] = asString(s['description']) ?? '';
+                    }
+                }
+            }
+            const grantTypes = isRecord(entry['grantTypes']) ? entry['grantTypes'] : {};
+            const flows = {};
+            if (isRecord(grantTypes['authorization_code'])) {
+                const ac = grantTypes['authorization_code'];
+                const tokenEndpoint = isRecord(ac['tokenEndpoint']) ? asString(ac['tokenEndpoint']['url']) : undefined;
+                const tokenUrl = asString(ac['tokenUrl']) ?? tokenEndpoint;
+                const authEndpoint = isRecord(ac['authorizationEndpoint'])
+                    ? asString(ac['authorizationEndpoint']['url'])
+                    : undefined;
+                const authorizationUrl = asString(ac['authorizationUrl']) ?? authEndpoint;
+                flows['authorizationCode'] = {
+                    ...(authorizationUrl !== undefined ? { authorizationUrl } : {}),
+                    ...(tokenUrl !== undefined ? { tokenUrl } : {}),
+                    ...(Object.keys(scopesMap).length > 0 ? { scopes: scopesMap } : {}),
+                };
+            }
+            if (isRecord(grantTypes['implicit'])) {
+                const imp = grantTypes['implicit'];
+                const loginEndpoint = isRecord(imp['loginEndpoint']) ? asString(imp['loginEndpoint']['url']) : undefined;
+                const authorizationUrl = asString(imp['authorizationUrl']) ?? loginEndpoint;
+                flows['implicit'] = {
+                    ...(authorizationUrl !== undefined ? { authorizationUrl } : {}),
+                    ...(Object.keys(scopesMap).length > 0 ? { scopes: scopesMap } : {}),
+                };
+            }
+            parsed.push({
+                name,
+                type: 'oauth2',
+                flows,
+                ...(description !== undefined ? { description } : {}),
+            });
+            continue;
+        }
+        skipped.push({
+            kind: 'securityScheme',
+            where: `/authorizations/${name}`,
+            reason: `unknown type "${type}"`,
+        });
+    }
+    return parsed;
+}