mirror of
https://github.com/mountain-loop/yaak.git
synced 2026-08-21 10:54:08 +02:00
1096 lines
34 KiB
TypeScript
1096 lines
34 KiB
TypeScript
import type {
|
|
Context,
|
|
Environment,
|
|
Folder,
|
|
HttpRequest,
|
|
HttpRequestHeader,
|
|
HttpUrlParameter,
|
|
PartialImportResources,
|
|
PluginDefinition,
|
|
Workspace,
|
|
} from "@yaakapp/api";
|
|
import type { ImportPluginResponse } from "@yaakapp/api/lib/plugins/ImporterPlugin";
|
|
import YAML from "yaml";
|
|
|
|
type AtLeast<T, K extends keyof T> = Partial<T> & Pick<T, K>;
|
|
type UnknownRecord = Record<string, unknown>;
|
|
type ImportResources = {
|
|
workspaces: AtLeast<Workspace, "name" | "id" | "model">[];
|
|
environments: AtLeast<Environment, "name" | "id" | "model" | "workspaceId" | "variables">[];
|
|
folders: AtLeast<Folder, "name" | "id" | "model" | "workspaceId">[];
|
|
httpRequests: AtLeast<HttpRequest, "name" | "id" | "model" | "workspaceId">[];
|
|
};
|
|
|
|
const HTTP_METHODS = ["delete", "get", "head", "options", "patch", "post", "put", "trace"];
|
|
const BODY_CONTENT_TYPE_PREFERENCE = [
|
|
"application/json",
|
|
"application/x-www-form-urlencoded",
|
|
"multipart/form-data",
|
|
"application/xml",
|
|
"text/plain",
|
|
];
|
|
const MAX_EXAMPLE_DEPTH = 8;
|
|
const MAX_EXAMPLE_PROPERTIES = 25;
|
|
const MAX_DESCRIPTION_ITEMS = 40;
|
|
const MAX_NAME_LENGTH = 100;
|
|
|
|
export const plugin: PluginDefinition = {
|
|
importer: {
|
|
name: "OpenAPI",
|
|
description: "Import OpenAPI collections",
|
|
onImport(_ctx: Context, args: { text: string }) {
|
|
return convertOpenApi(args.text);
|
|
},
|
|
},
|
|
};
|
|
|
|
export async function convertOpenApi(contents: string): Promise<ImportPluginResponse | undefined> {
|
|
const spec = parseSpec(contents);
|
|
if (!isOpenApiSpec(spec)) return undefined;
|
|
|
|
const importState = new ImportState(spec);
|
|
const workspace: ImportResources["workspaces"][0] = {
|
|
model: "workspace",
|
|
id: importState.generateId("workspace"),
|
|
name: stringAt(spec.info, "title") ?? "OpenAPI Import",
|
|
description: importInfoDescription(toRecord(spec.info)),
|
|
};
|
|
|
|
const resources: ImportResources = {
|
|
workspaces: [workspace],
|
|
environments: [],
|
|
folders: [],
|
|
httpRequests: [],
|
|
};
|
|
const baseUrl = importBaseUrl(spec);
|
|
const requestBaseUrl = baseUrl.length > 0 ? "${[baseUrl]}" : "";
|
|
|
|
if (baseUrl.length > 0) {
|
|
resources.environments.push({
|
|
model: "environment",
|
|
id: importState.generateId("environment"),
|
|
workspaceId: workspace.id,
|
|
name: "Global Variables",
|
|
variables: [{ name: "baseUrl", value: baseUrl }],
|
|
parentModel: "workspace",
|
|
parentId: null,
|
|
sortPriority: importState.nextSortPriority(),
|
|
});
|
|
}
|
|
|
|
const folderIdsByTag = new Map<string, string>();
|
|
const routeLabels = new Map<string, string>();
|
|
for (const tag of toArray(spec.tags)) {
|
|
const tagRecord = toRecord(tag);
|
|
const name = stringAt(tagRecord, "name");
|
|
if (name == null || folderIdsByTag.has(name)) continue;
|
|
|
|
const folder: ImportResources["folders"][0] = {
|
|
model: "folder",
|
|
id: importState.generateId("folder"),
|
|
workspaceId: workspace.id,
|
|
name,
|
|
description: importTagDescription(tagRecord),
|
|
folderId: null,
|
|
sortPriority: importState.nextSortPriority(),
|
|
};
|
|
resources.folders.push(folder);
|
|
folderIdsByTag.set(name, folder.id);
|
|
}
|
|
|
|
for (const [rawPath, rawPathItem] of Object.entries(toRecord(spec.paths))) {
|
|
const pathItem = importState.resolve(rawPathItem);
|
|
if (!isRecord(pathItem)) continue;
|
|
|
|
const pathParameters = toArray(pathItem.parameters);
|
|
for (const method of HTTP_METHODS) {
|
|
const operation = importState.resolve(pathItem[method]);
|
|
if (!isRecord(operation)) continue;
|
|
|
|
const folderId = findOrCreateFolderId({
|
|
folderIdsByTag,
|
|
importState,
|
|
operation,
|
|
resources,
|
|
workspaceId: workspace.id,
|
|
});
|
|
|
|
const request = importOperation({
|
|
importState,
|
|
method,
|
|
operation,
|
|
path: rawPath,
|
|
pathItem,
|
|
pathParameters,
|
|
requestBaseUrl,
|
|
spec,
|
|
workspaceId: workspace.id,
|
|
folderId,
|
|
});
|
|
routeLabels.set(request.id, `${method.toUpperCase()} ${rawPath}`);
|
|
resources.httpRequests.push(request);
|
|
}
|
|
}
|
|
|
|
if (resources.httpRequests.length === 0) return undefined;
|
|
|
|
disambiguateNames(resources.httpRequests, routeLabels);
|
|
|
|
return {
|
|
resources: deleteUndefinedAttrs(
|
|
convertTemplateSyntax({
|
|
environments: resources.environments,
|
|
folders: resources.folders,
|
|
grpcRequests: [],
|
|
httpRequests: resources.httpRequests,
|
|
websocketRequests: [],
|
|
workspaces: resources.workspaces,
|
|
}),
|
|
) as PartialImportResources,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Two operations sharing a summary are indistinguishable once imported, so the
|
|
* colliding ones get their route appended. Names that are already unique within
|
|
* their folder are left alone.
|
|
*/
|
|
function disambiguateNames(
|
|
requests: ImportResources["httpRequests"],
|
|
routeLabels: Map<string, string>,
|
|
): void {
|
|
const counts = new Map<string, number>();
|
|
for (const request of requests) {
|
|
const key = `${request.folderId ?? ""} ${request.name}`;
|
|
counts.set(key, (counts.get(key) ?? 0) + 1);
|
|
}
|
|
|
|
for (const request of requests) {
|
|
const key = `${request.folderId ?? ""} ${request.name}`;
|
|
const routeLabel = routeLabels.get(request.id);
|
|
if ((counts.get(key) ?? 0) < 2 || routeLabel == null) continue;
|
|
if (request.name === routeLabel) continue;
|
|
request.name = `${request.name} (${routeLabel})`;
|
|
}
|
|
}
|
|
|
|
function importOperation({
|
|
importState,
|
|
method,
|
|
operation,
|
|
path,
|
|
pathItem,
|
|
pathParameters,
|
|
requestBaseUrl,
|
|
spec,
|
|
workspaceId,
|
|
folderId,
|
|
}: {
|
|
importState: ImportState;
|
|
method: string;
|
|
operation: UnknownRecord;
|
|
path: string;
|
|
pathItem: UnknownRecord;
|
|
pathParameters: unknown[];
|
|
requestBaseUrl: string;
|
|
spec: UnknownRecord;
|
|
workspaceId: string;
|
|
folderId: string | null;
|
|
}): ImportResources["httpRequests"][0] {
|
|
importState.beginOperation();
|
|
const parameters = mergeParameters({
|
|
importState,
|
|
pathParameters,
|
|
operationParameters: toArray(operation.parameters),
|
|
});
|
|
const body = importBody({ importState, operation, parameters, spec });
|
|
const urlParameters = importUrlParameters({ importState, parameters });
|
|
const headers = mergeHeaders(
|
|
importHeaderParameters({ importState, parameters }),
|
|
body.headers,
|
|
importAcceptHeader({ importState, operation, spec }),
|
|
);
|
|
const authentication = importAuthentication({ importState, operation, spec });
|
|
|
|
// Built after everything else, so it can report the refs they left unresolved
|
|
const description = importOperationDescription({
|
|
importState,
|
|
operation,
|
|
parameters,
|
|
bodyContentType: body.bodyType,
|
|
});
|
|
|
|
return {
|
|
model: "http_request",
|
|
id: importState.generateId("http_request"),
|
|
workspaceId,
|
|
folderId,
|
|
name: importOperationName(operation, method, path),
|
|
description,
|
|
method: method.toUpperCase(),
|
|
url: buildOperationUrl(operationBaseUrl({ operation, pathItem, requestBaseUrl }), path),
|
|
urlParameters,
|
|
headers,
|
|
body: body.body,
|
|
bodyType: body.bodyType,
|
|
sortPriority: importState.nextSortPriority(),
|
|
...authentication,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* A parameter is identified by its name and location, and an operation may
|
|
* redeclare one from its path item to change it. Keeping both copies would
|
|
* import the stale one alongside the override, so the operation's wins.
|
|
*/
|
|
function mergeParameters({
|
|
importState,
|
|
pathParameters,
|
|
operationParameters,
|
|
}: {
|
|
importState: ImportState;
|
|
pathParameters: unknown[];
|
|
operationParameters: unknown[];
|
|
}): unknown[] {
|
|
const merged: unknown[] = [];
|
|
const indexByKey = new Map<string, number>();
|
|
|
|
for (const parameter of [...pathParameters, ...operationParameters]) {
|
|
const resolved = importState.resolve(parameter);
|
|
const name = stringAt(resolved, "name");
|
|
const location = stringAt(resolved, "in");
|
|
// Anything missing an identity can't be matched up, so it is kept as-is
|
|
if (name == null || location == null) {
|
|
merged.push(resolved);
|
|
continue;
|
|
}
|
|
|
|
const key = `${location} ${name}`;
|
|
const existing = indexByKey.get(key);
|
|
if (existing == null) {
|
|
indexByKey.set(key, merged.length);
|
|
merged.push(resolved);
|
|
} else {
|
|
merged[existing] = resolved;
|
|
}
|
|
}
|
|
|
|
return merged;
|
|
}
|
|
|
|
/** Operation-level `servers` beat path-level, which beat the spec-level base URL */
|
|
function operationBaseUrl({
|
|
operation,
|
|
pathItem,
|
|
requestBaseUrl,
|
|
}: {
|
|
operation: UnknownRecord;
|
|
pathItem: UnknownRecord;
|
|
requestBaseUrl: string;
|
|
}): string {
|
|
for (const servers of [operation.servers, pathItem.servers]) {
|
|
const override = toArray(servers)
|
|
.map((s) => interpolateServerUrl(toRecord(s)))
|
|
.find((url) => url.length > 0);
|
|
// Overrides are inlined rather than shared, since only the spec-level base
|
|
// URL becomes the baseUrl variable
|
|
if (override != null) return override;
|
|
}
|
|
return requestBaseUrl;
|
|
}
|
|
|
|
/**
|
|
* Swagger 2.0 declares response types up front in `produces`; OpenAPI 3 only
|
|
* lists them per response, so successful responses stand in. Both become an
|
|
* Accept header, which is what the Postman-based importer used to produce.
|
|
*/
|
|
function importAcceptHeader({
|
|
importState,
|
|
operation,
|
|
spec,
|
|
}: {
|
|
importState: ImportState;
|
|
operation: UnknownRecord;
|
|
spec: UnknownRecord;
|
|
}): HttpRequestHeader[] {
|
|
const produces =
|
|
toArray(operation.produces ?? spec.produces).find((c): c is string => typeof c === "string") ??
|
|
successResponseContentType(importState, operation);
|
|
// `*/*` is what a request accepts by default, so stating it just adds noise
|
|
if (produces == null || produces === "*/*") return [];
|
|
return [{ enabled: true, name: "Accept", value: produces }];
|
|
}
|
|
|
|
/** The content type of the first successful response, by the usual preference */
|
|
function successResponseContentType(
|
|
importState: ImportState,
|
|
operation: UnknownRecord,
|
|
): string | null {
|
|
for (const [status, response] of Object.entries(toRecord(operation.responses))) {
|
|
if (!status.startsWith("2") && status !== "default") continue;
|
|
|
|
const content = toRecord(toRecord(importState.resolve(response)).content);
|
|
const contentType = chooseContentType(Object.keys(content));
|
|
if (contentType != null) return contentType;
|
|
}
|
|
return null;
|
|
}
|
|
|
|
function parseSpec(contents: string): unknown {
|
|
try {
|
|
return JSON.parse(contents);
|
|
} catch {
|
|
// Fall through to YAML.
|
|
}
|
|
|
|
try {
|
|
return YAML.parse(contents);
|
|
} catch {
|
|
return null;
|
|
}
|
|
}
|
|
|
|
function isOpenApiSpec(value: unknown): value is UnknownRecord {
|
|
const spec = toRecord(value);
|
|
const openapi = stringAt(spec, "openapi");
|
|
const swagger = stringAt(spec, "swagger");
|
|
return isRecord(spec.paths) && (openapi?.startsWith("3.") === true || swagger === "2.0");
|
|
}
|
|
|
|
function importInfoDescription(info: UnknownRecord): string | undefined {
|
|
const parts = [
|
|
stringAt(info, "description"),
|
|
stringAt(info, "termsOfService")
|
|
? `Terms of service: ${stringAt(info, "termsOfService")}`
|
|
: null,
|
|
isRecord(info.contact) && stringAt(info.contact, "email")
|
|
? `Contact: ${stringAt(info.contact, "email")}`
|
|
: null,
|
|
isRecord(info.license) && stringAt(info.license, "name")
|
|
? `License: ${stringAt(info.license, "name")}${
|
|
stringAt(info.license, "url") ? ` (${stringAt(info.license, "url")})` : ""
|
|
}`
|
|
: null,
|
|
].filter(isPresent);
|
|
return parts.length > 0 ? parts.join("\n\n") : undefined;
|
|
}
|
|
|
|
function importTagDescription(tag: UnknownRecord): string | undefined {
|
|
const externalDocs = toRecord(tag.externalDocs);
|
|
const parts = [
|
|
stringAt(tag, "description"),
|
|
stringAt(externalDocs, "url")
|
|
? `${stringAt(externalDocs, "description") ?? "External docs"}: ${stringAt(externalDocs, "url")}`
|
|
: null,
|
|
].filter(isPresent);
|
|
return parts.length > 0 ? parts.join("\n\n") : undefined;
|
|
}
|
|
|
|
function importOperationName(operation: UnknownRecord, method: string, path: string): string {
|
|
return (
|
|
stringAt(operation, "summary") ??
|
|
stringAt(operation, "operationId") ??
|
|
firstLine(stringAt(operation, "description")) ??
|
|
`${method.toUpperCase()} ${path}`
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Some specs describe an operation without ever summarizing it, and the opening
|
|
* line is a far better name than the method and path. Paragraphs are left to the
|
|
* description, since a name that long is no easier to scan than the path.
|
|
*/
|
|
function firstLine(value: string | undefined): string | undefined {
|
|
const line = value?.split("\n").find((l) => l.trim().length > 0)?.trim();
|
|
if (line == null || line.length > MAX_NAME_LENGTH) return undefined;
|
|
return line;
|
|
}
|
|
|
|
function importOperationDescription({
|
|
importState,
|
|
operation,
|
|
parameters,
|
|
bodyContentType,
|
|
}: {
|
|
importState: ImportState;
|
|
operation: UnknownRecord;
|
|
parameters: unknown[];
|
|
bodyContentType: string | null;
|
|
}): string | undefined {
|
|
const parts: string[] = [];
|
|
const summary = stringAt(operation, "summary");
|
|
const description = stringAt(operation, "description");
|
|
const operationId = stringAt(operation, "operationId");
|
|
|
|
// Leads the description, since it changes whether the request should be used at all
|
|
if (operation.deprecated === true) {
|
|
parts.push("Deprecated.");
|
|
}
|
|
|
|
if (description != null) {
|
|
parts.push(description);
|
|
} else if (summary != null) {
|
|
parts.push(summary);
|
|
}
|
|
|
|
if (operationId != null) {
|
|
parts.push(`Operation ID: ${operationId}`);
|
|
}
|
|
|
|
const parameterDescriptions = parameters
|
|
.map((p) => importState.resolve(p))
|
|
.filter(isRecord)
|
|
.slice(0, MAX_DESCRIPTION_ITEMS)
|
|
.map((p) => {
|
|
const name = stringAt(p, "name") ?? "parameter";
|
|
const location = stringAt(p, "in") ?? "unknown";
|
|
const required = p.required === true ? ", required" : "";
|
|
const description = stringAt(p, "description");
|
|
return `- ${name} (${location}${required})${description ? `: ${description}` : ""}`;
|
|
});
|
|
if (parameterDescriptions.length > 0) {
|
|
parts.push(["Parameters:", ...parameterDescriptions].join("\n"));
|
|
}
|
|
|
|
const requestBody = importState.resolve(operation.requestBody);
|
|
if (isRecord(requestBody)) {
|
|
const content = toRecord(requestBody.content);
|
|
const contentTypes = Object.keys(content);
|
|
const bodyLines = [
|
|
stringAt(requestBody, "description"),
|
|
bodyContentType ? `Selected content type: ${bodyContentType}` : null,
|
|
contentTypes.length > 0 ? `Available content types: ${contentTypes.join(", ")}` : null,
|
|
].filter(isPresent);
|
|
if (bodyLines.length > 0) {
|
|
parts.push(["Request body:", ...bodyLines].join("\n"));
|
|
}
|
|
}
|
|
|
|
const responseDescriptions = Object.entries(toRecord(operation.responses))
|
|
.slice(0, MAX_DESCRIPTION_ITEMS)
|
|
.map(([status, response]) => {
|
|
const responseRecord = toRecord(importState.resolve(response));
|
|
return `- ${status}: ${stringAt(responseRecord, "description") ?? ""}`.trimEnd();
|
|
});
|
|
if (responseDescriptions.length > 0) {
|
|
parts.push(["Responses:", ...responseDescriptions].join("\n"));
|
|
}
|
|
|
|
const externalDocs = toRecord(operation.externalDocs);
|
|
if (stringAt(externalDocs, "url")) {
|
|
parts.push(
|
|
`${stringAt(externalDocs, "description") ?? "External docs"}: ${stringAt(externalDocs, "url")}`,
|
|
);
|
|
}
|
|
|
|
// Without this the parts these refs describe just come out blank
|
|
const unresolvedRefs = importState.unresolvedRefs().slice(0, MAX_DESCRIPTION_ITEMS);
|
|
if (unresolvedRefs.length > 0) {
|
|
parts.push(
|
|
[
|
|
"Unresolved references (point outside this document, so the parts they describe were left empty):",
|
|
...unresolvedRefs.map((ref) => `- ${ref}`),
|
|
].join("\n"),
|
|
);
|
|
}
|
|
|
|
return parts.length > 0 ? parts.join("\n\n") : undefined;
|
|
}
|
|
|
|
function findOrCreateFolderId({
|
|
folderIdsByTag,
|
|
importState,
|
|
operation,
|
|
resources,
|
|
workspaceId,
|
|
}: {
|
|
folderIdsByTag: Map<string, string>;
|
|
importState: ImportState;
|
|
operation: UnknownRecord;
|
|
resources: ImportResources;
|
|
workspaceId: string;
|
|
}): string | null {
|
|
const tag = toArray(operation.tags).find((t): t is string => typeof t === "string");
|
|
if (tag == null) return null;
|
|
|
|
const existingFolderId = folderIdsByTag.get(tag);
|
|
if (existingFolderId != null) return existingFolderId;
|
|
|
|
const folder: ImportResources["folders"][0] = {
|
|
model: "folder",
|
|
id: importState.generateId("folder"),
|
|
workspaceId,
|
|
name: tag,
|
|
folderId: null,
|
|
sortPriority: importState.nextSortPriority(),
|
|
};
|
|
resources.folders.push(folder);
|
|
folderIdsByTag.set(tag, folder.id);
|
|
return folder.id;
|
|
}
|
|
|
|
function buildOperationUrl(baseUrl: string, path: string): string {
|
|
return joinUrlParts(baseUrl, path.replaceAll(/{([^}/]+)}/g, ":$1"));
|
|
}
|
|
|
|
function importBaseUrl(spec: UnknownRecord): string {
|
|
const openApiServer = toArray(spec.servers)
|
|
.map((s) => toRecord(s))
|
|
.map((s) => interpolateServerUrl(s))
|
|
.find((url) => url.length > 0);
|
|
if (openApiServer != null) return openApiServer;
|
|
|
|
const host = stringAt(spec, "host");
|
|
if (host == null) return stringAt(spec, "basePath") ?? "";
|
|
|
|
const scheme = toArray(spec.schemes).find((s): s is string => typeof s === "string") ?? "https";
|
|
return joinUrlParts(`${scheme}://${host}`, stringAt(spec, "basePath") ?? "");
|
|
}
|
|
|
|
function interpolateServerUrl(server: UnknownRecord): string {
|
|
let url = stringAt(server, "url") ?? "";
|
|
for (const [name, variable] of Object.entries(toRecord(server.variables))) {
|
|
url = url.replaceAll(`{${name}}`, stringifyExampleValue(toRecord(variable).default));
|
|
}
|
|
return url;
|
|
}
|
|
|
|
function joinUrlParts(baseUrl: string, path: string): string {
|
|
if (baseUrl.length === 0) return path;
|
|
return `${trimTrailingSlashes(baseUrl)}/${trimLeadingSlashes(path)}`;
|
|
}
|
|
|
|
function trimLeadingSlashes(value: string): string {
|
|
let index = 0;
|
|
while (value[index] === "/") index++;
|
|
return value.slice(index);
|
|
}
|
|
|
|
function trimTrailingSlashes(value: string): string {
|
|
let index = value.length;
|
|
while (value[index - 1] === "/") index--;
|
|
return value.slice(0, index);
|
|
}
|
|
|
|
function importUrlParameters({
|
|
importState,
|
|
parameters,
|
|
}: {
|
|
importState: ImportState;
|
|
parameters: unknown[];
|
|
}): HttpUrlParameter[] {
|
|
return parameters
|
|
.map((p) => importState.resolve(p))
|
|
.filter(isRecord)
|
|
.filter((p) => stringAt(p, "in") === "query" || stringAt(p, "in") === "path")
|
|
.map((p) => ({
|
|
enabled: p.required === true,
|
|
name:
|
|
stringAt(p, "in") === "path"
|
|
? `:${stringAt(p, "name") ?? ""}`
|
|
: (stringAt(p, "name") ?? ""),
|
|
value: parameterExample(p, importState),
|
|
}))
|
|
.filter(({ name }) => name.length > 0);
|
|
}
|
|
|
|
function importHeaderParameters({
|
|
importState,
|
|
parameters,
|
|
}: {
|
|
importState: ImportState;
|
|
parameters: unknown[];
|
|
}): HttpRequestHeader[] {
|
|
return parameters
|
|
.map((p) => importState.resolve(p))
|
|
.filter(isRecord)
|
|
.filter((p) => stringAt(p, "in") === "header")
|
|
.map((p) => ({
|
|
enabled: p.required === true,
|
|
name: stringAt(p, "name") ?? "",
|
|
value: parameterExample(p, importState),
|
|
}))
|
|
.filter(({ name }) => name.length > 0);
|
|
}
|
|
|
|
function parameterExample(parameter: UnknownRecord, importState: ImportState): string {
|
|
const directExample = firstPresent(parameter.example, firstExampleValue(parameter.examples));
|
|
if (directExample != null) return stringifyExampleValue(directExample);
|
|
return stringifyExampleValue(schemaToExample(importState.resolve(parameter.schema), importState));
|
|
}
|
|
|
|
function importBody({
|
|
importState,
|
|
operation,
|
|
parameters,
|
|
spec,
|
|
}: {
|
|
importState: ImportState;
|
|
operation: UnknownRecord;
|
|
parameters: unknown[];
|
|
spec: UnknownRecord;
|
|
}): {
|
|
headers: HttpRequestHeader[];
|
|
body: Record<string, unknown>;
|
|
bodyType: string | null;
|
|
} {
|
|
const openApiRequestBody = importState.resolve(operation.requestBody);
|
|
if (isRecord(openApiRequestBody)) {
|
|
return importBodyFromContent(importState, toRecord(openApiRequestBody.content));
|
|
}
|
|
|
|
const bodyParameter = parameters
|
|
.map((p) => importState.resolve(p))
|
|
.find((p) => isRecord(p) && stringAt(p, "in") === "body");
|
|
if (isRecord(bodyParameter)) {
|
|
const contentType = toArray(operation.consumes ?? spec.consumes).find(
|
|
(c): c is string => typeof c === "string",
|
|
);
|
|
const bodyType = contentType ?? "application/json";
|
|
return {
|
|
headers: [{ enabled: true, name: "Content-Type", value: bodyType }],
|
|
bodyType,
|
|
body: {
|
|
text: formatBodyText(
|
|
schemaToExample(importState.resolve(bodyParameter.schema), importState),
|
|
),
|
|
},
|
|
};
|
|
}
|
|
|
|
const formParameters = parameters
|
|
.map((p) => importState.resolve(p))
|
|
.filter(isRecord)
|
|
.filter((p) => stringAt(p, "in") === "formData");
|
|
if (formParameters.length > 0) {
|
|
const contentType =
|
|
toArray(operation.consumes ?? spec.consumes).find((c): c is string => typeof c === "string") ??
|
|
(formParameters.some((p) => stringAt(p, "type") === "file")
|
|
? "multipart/form-data"
|
|
: "application/x-www-form-urlencoded");
|
|
return {
|
|
headers: [{ enabled: true, name: "Content-Type", value: contentType }],
|
|
bodyType: contentType,
|
|
body: {
|
|
form: formParameters.map((p) => ({
|
|
enabled: p.required === true,
|
|
name: stringAt(p, "name") ?? "",
|
|
value: parameterExample(p, importState),
|
|
})),
|
|
},
|
|
};
|
|
}
|
|
|
|
return { headers: [], body: {}, bodyType: null };
|
|
}
|
|
|
|
function importBodyFromContent(importState: ImportState, content: UnknownRecord) {
|
|
const contentType = chooseContentType(Object.keys(content));
|
|
if (contentType == null) return { headers: [], body: {}, bodyType: null };
|
|
|
|
const mediaType = toRecord(content[contentType]);
|
|
const example = mediaTypeExample(mediaType, importState);
|
|
|
|
if (
|
|
contentType === "application/x-www-form-urlencoded" ||
|
|
contentType === "multipart/form-data"
|
|
) {
|
|
return {
|
|
headers: [{ enabled: true, name: "Content-Type", value: contentType }],
|
|
bodyType: contentType,
|
|
body: {
|
|
form: schemaToFormParameters(importState.resolve(mediaType.schema), importState),
|
|
},
|
|
};
|
|
}
|
|
|
|
return {
|
|
headers: [{ enabled: true, name: "Content-Type", value: contentType }],
|
|
bodyType: contentType === "application/octet-stream" ? "binary" : contentType,
|
|
body: contentType === "application/octet-stream" ? {} : { text: formatBodyText(example) },
|
|
};
|
|
}
|
|
|
|
function chooseContentType(contentTypes: string[]): string | null {
|
|
for (const preference of BODY_CONTENT_TYPE_PREFERENCE) {
|
|
const exact = contentTypes.find((c) => c.toLowerCase() === preference);
|
|
if (exact != null) return exact;
|
|
}
|
|
return contentTypes[0] ?? null;
|
|
}
|
|
|
|
function mediaTypeExample(mediaType: UnknownRecord, importState: ImportState): unknown {
|
|
const directExample = firstPresent(mediaType.example, firstExampleValue(mediaType.examples));
|
|
if (directExample != null) return directExample;
|
|
return schemaToExample(importState.resolve(mediaType.schema), importState);
|
|
}
|
|
|
|
function schemaToFormParameters(schema: unknown, importState: ImportState) {
|
|
const resolvedSchema = toRecord(importState.resolve(schema));
|
|
const required = toArray(resolvedSchema.required).filter(
|
|
(name): name is string => typeof name === "string",
|
|
);
|
|
const properties = Object.entries(toRecord(resolvedSchema.properties)).slice(
|
|
0,
|
|
MAX_EXAMPLE_PROPERTIES,
|
|
);
|
|
|
|
return properties.map(([name, property]) => {
|
|
const resolvedProperty = toRecord(importState.resolve(property));
|
|
const example = schemaToExample(resolvedProperty, importState);
|
|
const base = {
|
|
enabled: required.includes(name),
|
|
name,
|
|
};
|
|
if (stringAt(resolvedProperty, "format") === "binary") {
|
|
return { ...base, file: "" };
|
|
}
|
|
return { ...base, value: stringifyExampleValue(example) };
|
|
});
|
|
}
|
|
|
|
function schemaToExample(
|
|
schema: unknown,
|
|
importState: ImportState,
|
|
depth = 0,
|
|
visitedRefs = new Set<string>(),
|
|
): unknown {
|
|
if (depth > MAX_EXAMPLE_DEPTH) return {};
|
|
|
|
const resolved = importState.resolve(schema, visitedRefs);
|
|
if (!isRecord(resolved)) return "";
|
|
|
|
const explicitExample = firstPresent(
|
|
resolved.example,
|
|
firstExampleValue(resolved.examples),
|
|
resolved.default,
|
|
);
|
|
if (explicitExample != null) return explicitExample;
|
|
|
|
const enumValues = toArray(resolved.enum);
|
|
if (enumValues.length > 0) return enumValues[0];
|
|
|
|
const allOf = toArray(resolved.allOf);
|
|
if (allOf.length > 0) {
|
|
return allOf.reduce<UnknownRecord>((merged, childSchema) => {
|
|
const childExample = schemaToExample(childSchema, importState, depth + 1, visitedRefs);
|
|
return isRecord(childExample) ? { ...merged, ...childExample } : merged;
|
|
}, {});
|
|
}
|
|
|
|
const oneOf = toArray(resolved.oneOf);
|
|
const anyOf = toArray(resolved.anyOf);
|
|
if (oneOf.length > 0 || anyOf.length > 0) {
|
|
return schemaToExample(oneOf[0] ?? anyOf[0], importState, depth + 1, visitedRefs);
|
|
}
|
|
|
|
const type = inferSchemaType(resolved);
|
|
if (type === "array") {
|
|
return [schemaToExample(resolved.items, importState, depth + 1, visitedRefs)];
|
|
}
|
|
if (type === "object") {
|
|
const required = toArray(resolved.required).filter(
|
|
(name): name is string => typeof name === "string",
|
|
);
|
|
const properties = Object.entries(toRecord(resolved.properties)).sort(([a], [b]) => {
|
|
const aRequired = required.includes(a);
|
|
const bRequired = required.includes(b);
|
|
return aRequired === bRequired ? 0 : aRequired ? -1 : 1;
|
|
});
|
|
|
|
return Object.fromEntries(
|
|
properties
|
|
.slice(0, MAX_EXAMPLE_PROPERTIES)
|
|
.map(([name, property]) => [
|
|
name,
|
|
schemaToExample(property, importState, depth + 1, visitedRefs),
|
|
]),
|
|
);
|
|
}
|
|
if (type === "integer" || type === "number") return 0;
|
|
if (type === "boolean") return false;
|
|
if (stringAt(resolved, "format") === "date-time") return "2026-01-01T00:00:00Z";
|
|
if (stringAt(resolved, "format") === "date") return "2026-01-01";
|
|
return "";
|
|
}
|
|
|
|
function inferSchemaType(schema: UnknownRecord): string {
|
|
const rawType = schema.type;
|
|
if (typeof rawType === "string") return rawType;
|
|
if (Array.isArray(rawType)) {
|
|
const nonNullType = rawType.find((t) => t !== "null");
|
|
if (typeof nonNullType === "string") return nonNullType;
|
|
}
|
|
if (isRecord(schema.properties) || isRecord(schema.additionalProperties)) return "object";
|
|
if (schema.items != null) return "array";
|
|
return "string";
|
|
}
|
|
|
|
function importAuthentication({
|
|
importState,
|
|
operation,
|
|
spec,
|
|
}: {
|
|
importState: ImportState;
|
|
operation: UnknownRecord;
|
|
spec: UnknownRecord;
|
|
}): Pick<HttpRequest, "authentication" | "authenticationType"> {
|
|
const security = operation.security ?? spec.security;
|
|
if (!Array.isArray(security) || security.length === 0) {
|
|
return { authenticationType: null, authentication: {} };
|
|
}
|
|
|
|
const schemes = {
|
|
...toRecord(toRecord(spec.components).securitySchemes),
|
|
...toRecord(spec.securityDefinitions),
|
|
};
|
|
for (const requirement of security) {
|
|
for (const [schemeName, rawScopes] of Object.entries(toRecord(requirement))) {
|
|
const scheme = toRecord(importState.resolve(schemes[schemeName]));
|
|
const type = stringAt(scheme, "type");
|
|
if (type === "oauth2") {
|
|
const oauth2 = importOAuth2(scheme, rawScopes);
|
|
if (oauth2 != null) return oauth2;
|
|
continue;
|
|
}
|
|
if (type === "apiKey") {
|
|
return { authenticationType: "apikey", authentication: importApiKey(scheme, schemeName) };
|
|
}
|
|
// Swagger 2.0 spells basic auth as its own type rather than an HTTP scheme
|
|
if (type === "basic" || (type === "http" && schemeIs(scheme, "basic"))) {
|
|
return {
|
|
authenticationType: "basic",
|
|
authentication: { username: "", password: "" },
|
|
};
|
|
}
|
|
if (type === "http" && schemeIs(scheme, "bearer")) {
|
|
return {
|
|
authenticationType: "bearer",
|
|
authentication: { token: "", prefix: "Bearer" },
|
|
};
|
|
}
|
|
}
|
|
}
|
|
|
|
return { authenticationType: null, authentication: {} };
|
|
}
|
|
|
|
function schemeIs(scheme: UnknownRecord, name: string): boolean {
|
|
return stringAt(scheme, "scheme")?.toLowerCase() === name;
|
|
}
|
|
|
|
/**
|
|
* The API key auth plugin can only write a header or a query parameter, so a
|
|
* cookie key becomes the Cookie header it would have ended up in, pre-filled
|
|
* with its name. Sending it as a header named after the cookie would just fail.
|
|
*/
|
|
function importApiKey(scheme: UnknownRecord, schemeName: string): Record<string, string> {
|
|
const key = stringAt(scheme, "name") ?? schemeName;
|
|
const location = stringAt(scheme, "in");
|
|
|
|
if (location === "cookie") {
|
|
return { location: "header", key: "Cookie", value: `${key}=` };
|
|
}
|
|
return { location: location === "query" ? "query" : "header", key, value: "" };
|
|
}
|
|
|
|
/**
|
|
* Maps an OpenAPI 3.x `flows` object or a Swagger 2.0 `flow` string onto the
|
|
* grant types the OAuth 2.0 auth plugin understands. Returns null when the
|
|
* scheme declares no flow this importer can map, so the caller keeps looking.
|
|
*/
|
|
function importOAuth2(
|
|
scheme: UnknownRecord,
|
|
rawScopes: unknown,
|
|
): Pick<HttpRequest, "authentication" | "authenticationType"> | null {
|
|
const scope = toArray(rawScopes)
|
|
.filter((s): s is string => typeof s === "string")
|
|
.join(" ");
|
|
|
|
const flows = toRecord(scheme.flows);
|
|
const swagger2Flow = stringAt(scheme, "flow");
|
|
const candidates: { grantType: string; flow: UnknownRecord }[] = [
|
|
{ grantType: "authorization_code", flow: toRecord(flows.authorizationCode) },
|
|
{ grantType: "client_credentials", flow: toRecord(flows.clientCredentials) },
|
|
{ grantType: "password", flow: toRecord(flows.password) },
|
|
{ grantType: "implicit", flow: toRecord(flows.implicit) },
|
|
];
|
|
|
|
// Swagger 2.0 puts the URLs on the scheme itself and names the flow differently
|
|
if (swagger2Flow != null) {
|
|
const grantType = {
|
|
accessCode: "authorization_code",
|
|
application: "client_credentials",
|
|
implicit: "implicit",
|
|
password: "password",
|
|
}[swagger2Flow];
|
|
if (grantType == null) return null;
|
|
candidates.unshift({ grantType, flow: scheme });
|
|
}
|
|
|
|
for (const { grantType, flow } of candidates) {
|
|
const authorizationUrl = stringAt(flow, "authorizationUrl");
|
|
const accessTokenUrl = stringAt(flow, "tokenUrl");
|
|
if (authorizationUrl == null && accessTokenUrl == null) continue;
|
|
|
|
const grantPatch =
|
|
grantType === "authorization_code"
|
|
? { authorizationUrl, accessTokenUrl, clientSecret: "" }
|
|
: grantType === "implicit"
|
|
? { authorizationUrl }
|
|
: grantType === "password"
|
|
? { accessTokenUrl, clientSecret: "", username: "", password: "" }
|
|
: { accessTokenUrl, clientSecret: "" };
|
|
|
|
return {
|
|
authenticationType: "oauth2",
|
|
authentication: {
|
|
grantType,
|
|
clientId: "",
|
|
headerPrefix: "Bearer",
|
|
...(scope.length > 0 ? { scope } : {}),
|
|
...grantPatch,
|
|
},
|
|
};
|
|
}
|
|
|
|
return null;
|
|
}
|
|
|
|
function mergeHeaders(...headerGroups: HttpRequestHeader[][]): HttpRequestHeader[] {
|
|
const headers: HttpRequestHeader[] = [];
|
|
for (const header of headerGroups.flat()) {
|
|
const existing = headers.find((h) => h.name.toLowerCase() === header.name.toLowerCase());
|
|
if (existing == null) {
|
|
headers.push(header);
|
|
}
|
|
}
|
|
return headers;
|
|
}
|
|
|
|
function formatBodyText(example: unknown): string {
|
|
return typeof example === "string" ? example : JSON.stringify(example, null, 2);
|
|
}
|
|
|
|
function stringifyExampleValue(value: unknown): string {
|
|
if (value == null) return "";
|
|
if (typeof value === "string") return value;
|
|
if (typeof value === "number" || typeof value === "boolean") return String(value);
|
|
return JSON.stringify(value);
|
|
}
|
|
|
|
function firstExampleValue(examples: unknown): unknown {
|
|
const firstExample = Object.values(toRecord(examples))[0];
|
|
if (isRecord(firstExample) && "value" in firstExample) return firstExample.value;
|
|
return firstExample;
|
|
}
|
|
|
|
function firstPresent(...values: unknown[]): unknown {
|
|
return values.find((value) => value !== undefined && value !== null);
|
|
}
|
|
|
|
function stringAt(record: unknown, key: string): string | undefined {
|
|
const value = toRecord(record)[key];
|
|
return typeof value === "string" ? value : undefined;
|
|
}
|
|
|
|
function toArray(value: unknown): unknown[] {
|
|
return Array.isArray(value) ? value : [];
|
|
}
|
|
|
|
function toRecord(value: unknown): UnknownRecord {
|
|
return isRecord(value) ? value : {};
|
|
}
|
|
|
|
function isRecord(value: unknown): value is UnknownRecord {
|
|
return value != null && typeof value === "object" && !Array.isArray(value);
|
|
}
|
|
|
|
function isPresent<T>(value: T | null | undefined): value is T {
|
|
return value != null && value !== "";
|
|
}
|
|
|
|
/** Recursively render all nested object properties */
|
|
function convertTemplateSyntax<T>(obj: T): T {
|
|
if (typeof obj === "string") {
|
|
// oxlint-disable-next-line no-template-curly-in-string -- Yaak template syntax
|
|
return obj.replaceAll(/{{\s*(_\.)?([^}]+)\s*}}/g, "${[$2]}") as T;
|
|
}
|
|
if (Array.isArray(obj) && obj != null) {
|
|
return obj.map(convertTemplateSyntax) as T;
|
|
}
|
|
if (typeof obj === "object" && obj != null) {
|
|
return Object.fromEntries(
|
|
Object.entries(obj).map(([k, v]) => [k, convertTemplateSyntax(v)]),
|
|
) as T;
|
|
}
|
|
return obj;
|
|
}
|
|
|
|
function deleteUndefinedAttrs<T>(obj: T): T {
|
|
if (Array.isArray(obj) && obj != null) {
|
|
return obj.map(deleteUndefinedAttrs) as T;
|
|
}
|
|
if (typeof obj === "object" && obj != null) {
|
|
return Object.fromEntries(
|
|
Object.entries(obj)
|
|
.filter(([, v]) => v !== undefined)
|
|
.map(([k, v]) => [k, deleteUndefinedAttrs(v)]),
|
|
) as T;
|
|
}
|
|
return obj;
|
|
}
|
|
|
|
class ImportState {
|
|
readonly #spec: UnknownRecord;
|
|
readonly #idCount: Partial<Record<string, number>> = {};
|
|
#sortPriority = 0;
|
|
#unresolvedRefs = new Set<string>();
|
|
|
|
constructor(spec: UnknownRecord) {
|
|
this.#spec = spec;
|
|
}
|
|
|
|
generateId(model: string): string {
|
|
this.#idCount[model] = (this.#idCount[model] ?? -1) + 1;
|
|
return `GENERATE_ID::${model.toUpperCase()}_${this.#idCount[model]}`;
|
|
}
|
|
|
|
nextSortPriority(): number {
|
|
return this.#sortPriority++;
|
|
}
|
|
|
|
/** Starts collecting unresolved refs for a single operation */
|
|
beginOperation(): void {
|
|
this.#unresolvedRefs = new Set();
|
|
}
|
|
|
|
/** Refs seen since `beginOperation` that point outside this document */
|
|
unresolvedRefs(): string[] {
|
|
return [...this.#unresolvedRefs];
|
|
}
|
|
|
|
resolve(value: unknown, visitedRefs = new Set<string>()): unknown {
|
|
if (!isRecord(value) || typeof value.$ref !== "string") return value;
|
|
if (visitedRefs.has(value.$ref)) return {};
|
|
|
|
const nextVisitedRefs = new Set(visitedRefs);
|
|
nextVisitedRefs.add(value.$ref);
|
|
|
|
// Refs into other documents can't be followed without fetching them, so
|
|
// record them and let the operation description report what went missing
|
|
if (!value.$ref.startsWith("#/")) {
|
|
this.#unresolvedRefs.add(value.$ref);
|
|
return value;
|
|
}
|
|
|
|
const resolved = value.$ref
|
|
.slice(2)
|
|
.split("/")
|
|
.map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"))
|
|
.reduce<unknown>((current, part) => toRecord(current)[part], this.#spec);
|
|
|
|
return this.resolve(resolved, nextVisitedRefs);
|
|
}
|
|
}
|