mirror of
https://github.com/mountain-loop/yaak.git
synced 2026-08-21 19:04:05 +02:00
1677 lines
53 KiB
TypeScript
1677 lines
53 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">[];
|
|
};
|
|
type ImportedAuthentication = Pick<HttpRequest, "authentication" | "authenticationType"> & {
|
|
headers: HttpRequestHeader[];
|
|
urlParameters: HttpUrlParameter[];
|
|
};
|
|
type AuthenticationVariableRegistry = Map<string, { name: string; value: string }>;
|
|
type OAuthVariableNames = { clientId: string; clientSecret: string };
|
|
type ServerOverrideVariable = { name: string; value: string };
|
|
|
|
const HTTP_METHODS = ["delete", "get", "head", "options", "patch", "post", "put", "query", "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 authenticationVariables: AuthenticationVariableRegistry = new Map();
|
|
const oauthVariablesByScheme = buildOAuthVariablesByScheme(importState, spec);
|
|
const serverOverrides = new Map<string, ServerOverrideVariable>();
|
|
const baseUrl = importBaseUrl(spec);
|
|
const serverEnvironments = importServerEnvironments(spec);
|
|
// A local spec has no document URL against which OpenAPI's implicit "/"
|
|
// server can resolve. Keep the shared variable even when its initial value
|
|
// is empty so users can configure the host once instead of editing requests.
|
|
const requestBaseUrl = "${[baseUrl]}";
|
|
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, operation } of pathItemOperations(pathItem, importState)) {
|
|
const folderId = findOrCreateFolderId({
|
|
folderIdsByTag,
|
|
importState,
|
|
operation,
|
|
resources,
|
|
workspaceId: workspace.id,
|
|
});
|
|
|
|
const request = importOperation({
|
|
importState,
|
|
method,
|
|
operation,
|
|
oauthVariablesByScheme,
|
|
path: rawPath,
|
|
pathItem,
|
|
pathParameters,
|
|
requestBaseUrl,
|
|
serverOverrides,
|
|
useDynamicServerUrls: serverEnvironments.length > 1,
|
|
spec,
|
|
workspaceId: workspace.id,
|
|
folderId,
|
|
authenticationVariables,
|
|
});
|
|
routeLabels.set(request.id, `${method.toUpperCase()} ${rawPath}`);
|
|
resources.httpRequests.push(request);
|
|
}
|
|
}
|
|
|
|
if (resources.httpRequests.some((request) => request.authenticationType === "oauth2")) {
|
|
const variableNames = new Set(
|
|
[...oauthVariablesByScheme.values()].flatMap(({ clientId, clientSecret }) => [
|
|
clientId,
|
|
clientSecret,
|
|
]),
|
|
);
|
|
if (
|
|
resources.httpRequests.some(
|
|
(request) =>
|
|
request.authenticationType === "oauth2" &&
|
|
Object.values(toRecord(request.authentication)).some(
|
|
(value) =>
|
|
typeof value === "string" && value.includes(templateVariable("baseUrlOrigin")),
|
|
),
|
|
)
|
|
) {
|
|
variableNames.add("baseUrlOrigin");
|
|
}
|
|
resources.environments[0]?.variables.push(
|
|
...[...variableNames].map((name) => ({ name, value: "" })),
|
|
);
|
|
}
|
|
|
|
if (resources.httpRequests.length === 0) return undefined;
|
|
|
|
const baseEnvironment = resources.environments[0];
|
|
if (baseEnvironment == null) return undefined;
|
|
baseEnvironment.variables.push(...authenticationVariables.values());
|
|
|
|
const environmentSpecificVariables = baseEnvironment.variables;
|
|
baseEnvironment.variables = [...serverOverrides.values()];
|
|
resources.environments.push(
|
|
...serverEnvironments.map(({ name, url }) => ({
|
|
model: "environment" as const,
|
|
id: importState.generateId("environment"),
|
|
workspaceId: workspace.id,
|
|
name,
|
|
variables: environmentSpecificVariables.map((variable) => ({
|
|
...variable,
|
|
value:
|
|
variable.name === "baseUrl"
|
|
? url
|
|
: variable.name === "baseUrlOrigin"
|
|
? serverUrlOrigin(url)
|
|
: variable.value,
|
|
})),
|
|
parentModel: "environment" as const,
|
|
parentId: null,
|
|
sortPriority: importState.nextSortPriority(),
|
|
})),
|
|
);
|
|
|
|
disambiguateNames(resources.httpRequests, routeLabels);
|
|
|
|
return {
|
|
resources: deleteUndefinedAttrs({
|
|
environments: resources.environments,
|
|
folders: resources.folders,
|
|
grpcRequests: [],
|
|
httpRequests: resources.httpRequests,
|
|
websocketRequests: [],
|
|
workspaces: resources.workspaces,
|
|
}) as PartialImportResources,
|
|
};
|
|
}
|
|
|
|
/** OpenAPI 3.2 adds QUERY plus a map for extension HTTP methods. */
|
|
function pathItemOperations(
|
|
pathItem: UnknownRecord,
|
|
importState: ImportState,
|
|
): { method: string; operation: UnknownRecord }[] {
|
|
const operations = HTTP_METHODS.flatMap((method) => {
|
|
const operation = importState.resolve(pathItem[method]);
|
|
return isRecord(operation) ? [{ method, operation }] : [];
|
|
});
|
|
|
|
for (const [method, rawOperation] of Object.entries(toRecord(pathItem.additionalOperations))) {
|
|
if (HTTP_METHODS.includes(method.toLowerCase())) continue;
|
|
const operation = importState.resolve(rawOperation);
|
|
if (isRecord(operation)) operations.push({ method, operation });
|
|
}
|
|
return operations;
|
|
}
|
|
|
|
/**
|
|
* 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,
|
|
oauthVariablesByScheme,
|
|
path,
|
|
pathItem,
|
|
pathParameters,
|
|
requestBaseUrl,
|
|
serverOverrides,
|
|
useDynamicServerUrls,
|
|
spec,
|
|
workspaceId,
|
|
folderId,
|
|
authenticationVariables,
|
|
}: {
|
|
importState: ImportState;
|
|
method: string;
|
|
operation: UnknownRecord;
|
|
oauthVariablesByScheme: Map<string, OAuthVariableNames>;
|
|
path: string;
|
|
pathItem: UnknownRecord;
|
|
pathParameters: unknown[];
|
|
requestBaseUrl: string;
|
|
serverOverrides: Map<string, ServerOverrideVariable>;
|
|
useDynamicServerUrls: boolean;
|
|
spec: UnknownRecord;
|
|
workspaceId: string;
|
|
folderId: string | null;
|
|
authenticationVariables: AuthenticationVariableRegistry;
|
|
}): ImportResources["httpRequests"][0] {
|
|
importState.beginOperation();
|
|
const parameters = mergeParameters({
|
|
importState,
|
|
pathParameters,
|
|
operationParameters: toArray(operation.parameters),
|
|
});
|
|
const body = importBody({ importState, operation, parameters, spec });
|
|
const authentication = importAuthentication({
|
|
authenticationVariables,
|
|
importState,
|
|
oauthVariablesByScheme,
|
|
operation,
|
|
spec,
|
|
useDynamicServerUrls,
|
|
});
|
|
const pathExampleValues = new Map(
|
|
parameters
|
|
.map((p) => importState.resolve(p))
|
|
.filter(isRecord)
|
|
.filter((p) => stringAt(p, "in") === "path" && stringAt(p, "name") != null)
|
|
.map((p) => [stringAt(p, "name") as string, parameterExample(p, importState)] as const),
|
|
);
|
|
const { url, placeholderNames } = buildOperationUrl(
|
|
operationBaseUrl({ operation, pathItem, requestBaseUrl, serverOverrides }),
|
|
path,
|
|
pathExampleValues,
|
|
);
|
|
const urlParameters = [
|
|
...importUrlParameters({ importState, parameters, placeholderNames }),
|
|
...authentication.urlParameters,
|
|
];
|
|
const headers = mergeHeaders(
|
|
authentication.headers,
|
|
importHeaderParameters({ importState, parameters }),
|
|
importCookieHeader({ importState, parameters }),
|
|
body.headers,
|
|
importAcceptHeader({ importState, operation, spec }),
|
|
);
|
|
const {
|
|
headers: _authenticationHeaders,
|
|
urlParameters: _authenticationParameters,
|
|
...auth
|
|
} = authentication;
|
|
|
|
// 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,
|
|
urlParameters,
|
|
headers,
|
|
body: body.body,
|
|
bodyType: body.bodyType,
|
|
sortPriority: importState.nextSortPriority(),
|
|
...auth,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* 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,
|
|
serverOverrides,
|
|
}: {
|
|
operation: UnknownRecord;
|
|
pathItem: UnknownRecord;
|
|
requestBaseUrl: string;
|
|
serverOverrides: Map<string, ServerOverrideVariable>;
|
|
}): string {
|
|
for (const servers of [operation.servers, pathItem.servers]) {
|
|
const override = toArray(servers)
|
|
.map((s) => interpolateServerUrl(toRecord(s)))
|
|
.find((url) => url.length > 0);
|
|
if (override != null) {
|
|
let variable = serverOverrides.get(override);
|
|
if (variable == null) {
|
|
const suffix = serverOverrides.size === 0 ? "" : String(serverOverrides.size + 1);
|
|
variable = { name: `serverUrl${suffix}`, value: override };
|
|
serverOverrides.set(override, variable);
|
|
}
|
|
return `\${[${variable.name}]}`;
|
|
}
|
|
}
|
|
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;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* The spec requires string versions, but unquoted YAML like `swagger: 2.0`
|
|
* parses as a number and such documents are common enough to accept.
|
|
*/
|
|
function isOpenApiSpec(value: unknown): value is UnknownRecord {
|
|
const spec = toRecord(value);
|
|
const openapi = versionString(spec.openapi);
|
|
return isRecord(spec.paths) && (/^3(\.|$)/.test(openapi ?? "") || isSwagger2(spec));
|
|
}
|
|
|
|
function isSwagger2(spec: UnknownRecord): boolean {
|
|
const swagger = versionString(spec.swagger);
|
|
return swagger === "2.0" || swagger === "2";
|
|
}
|
|
|
|
function versionString(value: unknown): string | undefined {
|
|
if (typeof value === "string") return value;
|
|
if (typeof value === "number") return String(value);
|
|
return undefined;
|
|
}
|
|
|
|
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;
|
|
}
|
|
|
|
/**
|
|
* Yaak's `:name` placeholders only substitute when they span a whole path
|
|
* segment. A template elsewhere in a segment, like `/report.{format}`, would
|
|
* import as text that never substitutes, and its leftover parameter would then
|
|
* be sent as a query parameter — so those get their example inlined instead.
|
|
*/
|
|
function buildOperationUrl(
|
|
baseUrl: string,
|
|
path: string,
|
|
inlineValues: Map<string, string>,
|
|
): { url: string; placeholderNames: Set<string> } {
|
|
const placeholderNames = new Set<string>();
|
|
const converted = path.replaceAll(/(^|\/){([^}/]+)}(?=[/?#:]|$)/g, (_, prefix, name) => {
|
|
placeholderNames.add(name);
|
|
return `${prefix}:${name}`;
|
|
});
|
|
const inlined = converted.replaceAll(/{([^}/]+)}/g, (match, name) => {
|
|
const value = inlineValues.get(name);
|
|
return value == null || value === "" ? match : value;
|
|
});
|
|
return { url: joinUrlParts(baseUrl, inlined), placeholderNames };
|
|
}
|
|
|
|
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 trimTrailingSlashes(joinUrlParts(`${scheme}://${host}`, stringAt(spec, "basePath") ?? ""));
|
|
}
|
|
|
|
function importServerEnvironments(spec: UnknownRecord): { name: string; url: string }[] {
|
|
const servers = toArray(spec.servers)
|
|
.map(toRecord)
|
|
.map((server, index) => ({
|
|
name: stringAt(server, "description")?.trim() || `Server ${index + 1}`,
|
|
url: interpolateServerUrl(server),
|
|
}))
|
|
.filter(({ url }) => url.length > 0);
|
|
if (servers.length === 0) {
|
|
const hasSwaggerServer =
|
|
isSwagger2(spec) && (stringAt(spec, "host") != null || stringAt(spec, "basePath") != null);
|
|
return [
|
|
{
|
|
name: hasSwaggerServer ? "Server 1" : "Default",
|
|
url: hasSwaggerServer ? importBaseUrl(spec) : "",
|
|
},
|
|
];
|
|
}
|
|
|
|
const nameCounts = new Map<string, number>();
|
|
return servers.map((server) => {
|
|
const count = (nameCounts.get(server.name) ?? 0) + 1;
|
|
nameCounts.set(server.name, count);
|
|
return { ...server, name: count === 1 ? server.name : `${server.name} ${count}` };
|
|
});
|
|
}
|
|
|
|
function serverUrlOrigin(value: string): string {
|
|
try {
|
|
const origin = new URL(value).origin;
|
|
return origin === "null" ? "" : origin;
|
|
} catch {
|
|
if (!value.startsWith("//")) return "";
|
|
try {
|
|
return `//${new URL(`https:${value}`).host}`;
|
|
} catch {
|
|
return "";
|
|
}
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Request URLs are `${[baseUrl]}/path`, so a trailing slash here would put a
|
|
* double slash on the wire. Trimming also turns a bare `/` server into "",
|
|
* which renders the same URLs without a protocol-relative `//path`.
|
|
*/
|
|
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 trimTrailingSlashes(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,
|
|
placeholderNames,
|
|
}: {
|
|
importState: ImportState;
|
|
parameters: unknown[];
|
|
placeholderNames: Set<string>;
|
|
}): HttpUrlParameter[] {
|
|
return parameters
|
|
.map((p) => importState.resolve(p))
|
|
.filter(isRecord)
|
|
.filter(
|
|
(p) =>
|
|
stringAt(p, "in") === "query" ||
|
|
(stringAt(p, "in") === "path" && placeholderNames.has(stringAt(p, "name") ?? "")),
|
|
)
|
|
.map((p) => ({
|
|
// Path parameters are required by definition, and a disabled one would
|
|
// leave the literal `:name` in the sent URL even for sloppy specs that
|
|
// omit `required: true`
|
|
enabled: p.required === true || stringAt(p, "in") === "path",
|
|
name:
|
|
stringAt(p, "in") === "path"
|
|
? `:${stringAt(p, "name") ?? ""}`
|
|
: (stringAt(p, "name") ?? ""),
|
|
value: parameterExample(p, importState),
|
|
}))
|
|
.filter(({ name }) => name.length > 0);
|
|
}
|
|
|
|
// The spec says header parameters with these names SHALL be ignored; Accept and
|
|
// Content-Type come from the operation's media types, Authorization from its
|
|
// security requirements
|
|
const IGNORED_HEADER_PARAMETERS = new Set(["accept", "authorization", "content-type"]);
|
|
|
|
function importHeaderParameters({
|
|
importState,
|
|
parameters,
|
|
}: {
|
|
importState: ImportState;
|
|
parameters: unknown[];
|
|
}): HttpRequestHeader[] {
|
|
return parameters
|
|
.map((p) => importState.resolve(p))
|
|
.filter(isRecord)
|
|
.filter((p) => stringAt(p, "in") === "header")
|
|
.filter((p) => !IGNORED_HEADER_PARAMETERS.has((stringAt(p, "name") ?? "").toLowerCase()))
|
|
.map((p) => ({
|
|
enabled: p.required === true,
|
|
name: stringAt(p, "name") ?? "",
|
|
value: parameterExample(p, importState),
|
|
}))
|
|
.filter(({ name }) => name.length > 0);
|
|
}
|
|
|
|
/** Yaak has no cookie parameter row, so cookie parameters become the header they would produce */
|
|
function importCookieHeader({
|
|
importState,
|
|
parameters,
|
|
}: {
|
|
importState: ImportState;
|
|
parameters: unknown[];
|
|
}): HttpRequestHeader[] {
|
|
const cookieParameters = parameters
|
|
.map((p) => importState.resolve(p))
|
|
.filter(isRecord)
|
|
.filter((p) => stringAt(p, "in") === "cookie")
|
|
.filter((p) => (stringAt(p, "name") ?? "").length > 0);
|
|
if (cookieParameters.length === 0) return [];
|
|
|
|
return [
|
|
{
|
|
enabled: cookieParameters.some((p) => p.required === true),
|
|
name: "Cookie",
|
|
value: cookieParameters
|
|
.map((p) => `${stringAt(p, "name")}=${parameterExample(p, importState)}`)
|
|
.join("; "),
|
|
},
|
|
];
|
|
}
|
|
|
|
function parameterExample(parameter: UnknownRecord, importState: ImportState): string {
|
|
const directExample = firstPresent(
|
|
parameter.example,
|
|
firstExampleValue(parameter.examples, importState),
|
|
);
|
|
if (directExample != null) return stringifyExampleValue(directExample);
|
|
const example = stringifyExampleValue(
|
|
schemaToExample(importState.resolve(parameter.schema), importState),
|
|
);
|
|
// An empty path segment makes a URL that matches nothing, so the name at
|
|
// least keeps the request sendable and shows what belongs there
|
|
if (example === "" && stringAt(parameter, "in") === "path") {
|
|
return stringAt(parameter, "name") ?? "";
|
|
}
|
|
return example;
|
|
}
|
|
|
|
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",
|
|
) ?? "application/json";
|
|
return {
|
|
headers: [{ enabled: true, name: "Content-Type", value: contentType }],
|
|
bodyType: yaakBodyType(contentType),
|
|
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 bodyType = yaakBodyType(contentType);
|
|
|
|
if (bodyType === "application/x-www-form-urlencoded" || bodyType === "multipart/form-data") {
|
|
return {
|
|
headers: [{ enabled: true, name: "Content-Type", value: contentType }],
|
|
bodyType,
|
|
body: {
|
|
form: schemaToFormParameters(importState.resolve(mediaType.schema), importState),
|
|
},
|
|
};
|
|
}
|
|
|
|
return {
|
|
headers: [{ enabled: true, name: "Content-Type", value: contentType }],
|
|
bodyType,
|
|
body:
|
|
bodyType === "binary"
|
|
? {}
|
|
: { text: formatBodyText(mediaTypeExample(mediaType, importState)) },
|
|
};
|
|
}
|
|
|
|
function chooseContentType(contentTypes: string[]): string | null {
|
|
for (const preference of BODY_CONTENT_TYPE_PREFERENCE) {
|
|
const exact = contentTypes.find((c) => mediaTypeOf(c) === preference);
|
|
if (exact != null) return exact;
|
|
}
|
|
return contentTypes[0] ?? null;
|
|
}
|
|
|
|
function mediaTypeOf(contentType: string): string {
|
|
return contentType.toLowerCase().split(";")[0]?.trim() ?? "";
|
|
}
|
|
|
|
/**
|
|
* Yaak's body editors key off a fixed set of body types, while the Content-Type
|
|
* header keeps the spec's exact media type. Anything unrecognized becomes
|
|
* "other", the app's plain-text body with an explicit Content-Type.
|
|
*/
|
|
function yaakBodyType(contentType: string): string {
|
|
const mediaType = mediaTypeOf(contentType);
|
|
if (mediaType === "application/json" || mediaType.endsWith("+json")) return "application/json";
|
|
if (mediaType === "application/xml" || mediaType === "text/xml" || mediaType.endsWith("+xml")) {
|
|
return "text/xml";
|
|
}
|
|
if (mediaType === "application/x-www-form-urlencoded" || mediaType === "multipart/form-data") {
|
|
return mediaType;
|
|
}
|
|
if (mediaType === "application/octet-stream") return "binary";
|
|
return "other";
|
|
}
|
|
|
|
function mediaTypeExample(mediaType: UnknownRecord, importState: ImportState): unknown {
|
|
const directExample = firstPresent(
|
|
mediaType.example,
|
|
firstExampleValue(mediaType.examples, importState),
|
|
);
|
|
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 sources = [
|
|
...toArray(resolvedSchema.allOf).map((s) => toRecord(importState.resolve(s))),
|
|
resolvedSchema,
|
|
];
|
|
const required = sources
|
|
.flatMap((s) => toArray(s.required))
|
|
.filter((name): name is string => typeof name === "string");
|
|
const properties = [
|
|
...new Map(sources.flatMap((s) => Object.entries(toRecord(s.properties)))).entries(),
|
|
].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, importState),
|
|
resolved.default,
|
|
);
|
|
if (explicitExample != null) return coerceToDeclaredType(explicitExample, resolved);
|
|
|
|
const enumValues = toArray(resolved.enum);
|
|
if (enumValues.length > 0) return enumValues[0];
|
|
|
|
const allOf = toArray(resolved.allOf);
|
|
if (allOf.length > 0) {
|
|
const merged = allOf.reduce<UnknownRecord>((merged, childSchema) => {
|
|
const childExample = schemaToExample(childSchema, importState, depth + 1, visitedRefs);
|
|
return isRecord(childExample) ? { ...merged, ...childExample } : merged;
|
|
}, {});
|
|
// Sibling properties are their own constraint alongside the allOf branches
|
|
return { ...merged, ...objectPropertiesExample(resolved, importState, depth, visitedRefs) };
|
|
}
|
|
|
|
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") {
|
|
return objectPropertiesExample(resolved, importState, depth, visitedRefs);
|
|
}
|
|
if (type === "integer" || type === "number") return 0;
|
|
if (type === "boolean") return false;
|
|
return FORMAT_EXAMPLES[stringAt(resolved, "format") ?? ""] ?? "";
|
|
}
|
|
|
|
const FORMAT_EXAMPLES: Record<string, string> = {
|
|
"date-time": "2026-01-01T00:00:00Z",
|
|
date: "2026-01-01",
|
|
email: "user@example.com",
|
|
hostname: "example.com",
|
|
ipv4: "127.0.0.1",
|
|
ipv6: "::1",
|
|
uri: "https://example.com",
|
|
url: "https://example.com",
|
|
uuid: "00000000-0000-0000-0000-000000000000",
|
|
};
|
|
|
|
/**
|
|
* YAML coerces unquoted scalars, so specs routinely carry `example: 12345` on a
|
|
* `type: string` field. Sending the number fails the spec's own schema, and the
|
|
* declared type is the author's stated intent.
|
|
*/
|
|
function coerceToDeclaredType(example: unknown, schema: UnknownRecord): unknown {
|
|
const rawType = schema.type;
|
|
const declared =
|
|
typeof rawType === "string"
|
|
? rawType
|
|
: Array.isArray(rawType)
|
|
? rawType.find((t) => t !== "null")
|
|
: null;
|
|
|
|
if (declared === "string" && (typeof example === "number" || typeof example === "boolean")) {
|
|
return String(example);
|
|
}
|
|
if (
|
|
(declared === "integer" || declared === "number") &&
|
|
typeof example === "string" &&
|
|
example.trim() !== "" &&
|
|
Number.isFinite(Number(example))
|
|
) {
|
|
return Number(example);
|
|
}
|
|
return example;
|
|
}
|
|
|
|
function objectPropertiesExample(
|
|
schema: UnknownRecord,
|
|
importState: ImportState,
|
|
depth: number,
|
|
visitedRefs: Set<string>,
|
|
): UnknownRecord {
|
|
const required = toArray(schema.required).filter(
|
|
(name): name is string => typeof name === "string",
|
|
);
|
|
const properties = Object.entries(toRecord(schema.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),
|
|
]),
|
|
);
|
|
}
|
|
|
|
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({
|
|
authenticationVariables,
|
|
importState,
|
|
oauthVariablesByScheme,
|
|
operation,
|
|
spec,
|
|
useDynamicServerUrls,
|
|
}: {
|
|
authenticationVariables: AuthenticationVariableRegistry;
|
|
importState: ImportState;
|
|
oauthVariablesByScheme: Map<string, OAuthVariableNames>;
|
|
operation: UnknownRecord;
|
|
spec: UnknownRecord;
|
|
useDynamicServerUrls: boolean;
|
|
}): ImportedAuthentication {
|
|
const security = operation.security ?? spec.security;
|
|
if (Array.isArray(operation.security) && operation.security.length === 0) {
|
|
return { ...emptyAuthentication(), authenticationType: "none" };
|
|
}
|
|
if (!Array.isArray(security) || security.length === 0) {
|
|
return emptyAuthentication();
|
|
}
|
|
|
|
// Security Requirement Objects are alternatives. If any alternative is
|
|
// empty, authentication is optional regardless of where it appears.
|
|
if (
|
|
security.some((requirement) => isRecord(requirement) && Object.keys(requirement).length === 0)
|
|
) {
|
|
return { ...emptyAuthentication(), authenticationType: "none" };
|
|
}
|
|
|
|
const schemes = {
|
|
...toRecord(toRecord(spec.components).securitySchemes),
|
|
...toRecord(spec.securityDefinitions),
|
|
};
|
|
for (const rawRequirement of security) {
|
|
if (!isRecord(rawRequirement)) continue;
|
|
|
|
const imported = importSecurityRequirement({
|
|
authenticationVariables,
|
|
importState,
|
|
oauthVariablesByScheme,
|
|
requirement: rawRequirement,
|
|
schemes,
|
|
spec,
|
|
useDynamicServerUrls,
|
|
});
|
|
if (imported != null) return imported;
|
|
}
|
|
|
|
return emptyAuthentication();
|
|
}
|
|
|
|
function importSecurityRequirement({
|
|
authenticationVariables,
|
|
importState,
|
|
oauthVariablesByScheme,
|
|
requirement,
|
|
schemes,
|
|
spec,
|
|
useDynamicServerUrls,
|
|
}: {
|
|
authenticationVariables: AuthenticationVariableRegistry;
|
|
importState: ImportState;
|
|
oauthVariablesByScheme: Map<string, OAuthVariableNames>;
|
|
requirement: UnknownRecord;
|
|
schemes: UnknownRecord;
|
|
spec: UnknownRecord;
|
|
useDynamicServerUrls: boolean;
|
|
}): ImportedAuthentication | null {
|
|
const entries = Object.entries(requirement);
|
|
const headers: HttpRequestHeader[] = [];
|
|
const urlParameters: HttpUrlParameter[] = [];
|
|
let primaryAuthentication: Pick<HttpRequest, "authentication" | "authenticationType"> | null =
|
|
null;
|
|
|
|
for (const [schemeName, rawScopes] of entries) {
|
|
const scheme = toRecord(importState.resolve(schemes[schemeName]));
|
|
const type = stringAt(scheme, "type");
|
|
if (type === "apiKey") {
|
|
const variable = registerAuthenticationVariable(authenticationVariables, schemeName, "key");
|
|
if (entries.length === 1) {
|
|
primaryAuthentication = {
|
|
authenticationType: "apikey",
|
|
authentication: importApiKey(scheme, schemeName, variable),
|
|
};
|
|
} else {
|
|
materializeApiKey(scheme, schemeName, variable, headers, urlParameters);
|
|
}
|
|
continue;
|
|
}
|
|
|
|
let candidate: Pick<HttpRequest, "authentication" | "authenticationType"> | null = null;
|
|
if (type === "oauth2") {
|
|
candidate = importOAuth2(
|
|
scheme,
|
|
rawScopes,
|
|
importBaseUrl(spec),
|
|
oauthVariablesByScheme.get(schemeName) ?? {
|
|
clientId: "oauth_client_id",
|
|
clientSecret: "oauth_client_secret",
|
|
},
|
|
useDynamicServerUrls,
|
|
);
|
|
} else if (type === "openIdConnect") {
|
|
const token = registerAuthenticationVariable(authenticationVariables, schemeName, "token");
|
|
candidate = {
|
|
authenticationType: "bearer",
|
|
authentication: { token: templateVariable(token), prefix: "Bearer" },
|
|
};
|
|
} else if (type === "basic" || (type === "http" && schemeIs(scheme, "basic"))) {
|
|
const username = registerAuthenticationVariable(
|
|
authenticationVariables,
|
|
schemeName,
|
|
"username",
|
|
);
|
|
const password = registerAuthenticationVariable(
|
|
authenticationVariables,
|
|
schemeName,
|
|
"password",
|
|
);
|
|
candidate = {
|
|
authenticationType: "basic",
|
|
authentication: {
|
|
username: templateVariable(username),
|
|
password: templateVariable(password),
|
|
},
|
|
};
|
|
} else if (type === "http" && schemeIs(scheme, "bearer")) {
|
|
const token = registerAuthenticationVariable(authenticationVariables, schemeName, "token");
|
|
candidate = {
|
|
authenticationType: "bearer",
|
|
authentication: { token: templateVariable(token), prefix: "Bearer" },
|
|
};
|
|
}
|
|
|
|
// A requirement is an AND. Yaak can combine one auth plugin with explicit
|
|
// API-key parameters, but cannot represent two auth plugins on one request.
|
|
if (candidate == null || primaryAuthentication != null) return null;
|
|
primaryAuthentication = candidate;
|
|
}
|
|
|
|
return {
|
|
...(primaryAuthentication ?? {
|
|
authenticationType: entries.length > 1 ? "none" : null,
|
|
authentication: {},
|
|
}),
|
|
headers,
|
|
urlParameters,
|
|
};
|
|
}
|
|
|
|
function emptyAuthentication(): ImportedAuthentication {
|
|
return {
|
|
authenticationType: null,
|
|
authentication: {},
|
|
headers: [],
|
|
urlParameters: [],
|
|
};
|
|
}
|
|
|
|
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,
|
|
variableName: string,
|
|
): Record<string, string> {
|
|
const key = stringAt(scheme, "name") ?? schemeName;
|
|
const location = stringAt(scheme, "in");
|
|
const value = templateVariable(variableName);
|
|
|
|
if (location === "cookie") {
|
|
return { location: "header", key: "Cookie", value: `${key}=${value}` };
|
|
}
|
|
return { location: location === "query" ? "query" : "header", key, value };
|
|
}
|
|
|
|
function materializeApiKey(
|
|
scheme: UnknownRecord,
|
|
schemeName: string,
|
|
variableName: string,
|
|
headers: HttpRequestHeader[],
|
|
urlParameters: HttpUrlParameter[],
|
|
): void {
|
|
const key = stringAt(scheme, "name") ?? schemeName;
|
|
const location = stringAt(scheme, "in");
|
|
const value = templateVariable(variableName);
|
|
if (location === "query") {
|
|
urlParameters.push({ enabled: true, name: key, value });
|
|
} else if (location === "cookie") {
|
|
headers.push({ enabled: true, name: "Cookie", value: `${key}=${value}` });
|
|
} else {
|
|
headers.push({ enabled: true, name: key, value });
|
|
}
|
|
}
|
|
|
|
function registerAuthenticationVariable(
|
|
variables: AuthenticationVariableRegistry,
|
|
schemeName: string,
|
|
field: string,
|
|
): string {
|
|
const identity = JSON.stringify([schemeName, field]);
|
|
const existing = variables.get(identity);
|
|
if (existing != null) return existing.name;
|
|
|
|
const schemePart = schemeName
|
|
.replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2")
|
|
.replaceAll(/[^a-zA-Z0-9]+/g, "_")
|
|
.replaceAll(/^_+|_+$/g, "")
|
|
.toLowerCase();
|
|
const baseName = `auth_${schemePart || "security"}_${field}`;
|
|
let name = baseName;
|
|
let suffix = 2;
|
|
const names = new Set([...variables.values()].map((variable) => variable.name));
|
|
while (names.has(name)) {
|
|
name = `${baseName}_${suffix++}`;
|
|
}
|
|
variables.set(identity, { name, value: "" });
|
|
return name;
|
|
}
|
|
|
|
function templateVariable(name: string): string {
|
|
return `\${[${name}]}`;
|
|
}
|
|
|
|
/**
|
|
* 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,
|
|
baseUrl: string,
|
|
variableNames: OAuthVariableNames,
|
|
useDynamicServerUrls: boolean,
|
|
): 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 = resolveOAuthUrl(
|
|
stringAt(flow, "authorizationUrl"),
|
|
baseUrl,
|
|
useDynamicServerUrls,
|
|
);
|
|
const accessTokenUrl = resolveOAuthUrl(
|
|
stringAt(flow, "tokenUrl"),
|
|
baseUrl,
|
|
useDynamicServerUrls,
|
|
);
|
|
if (authorizationUrl == null && accessTokenUrl == null) continue;
|
|
|
|
const grantPatch =
|
|
grantType === "authorization_code"
|
|
? {
|
|
authorizationUrl,
|
|
accessTokenUrl,
|
|
clientSecret: templateVariable(variableNames.clientSecret),
|
|
}
|
|
: grantType === "implicit"
|
|
? { authorizationUrl }
|
|
: grantType === "password"
|
|
? {
|
|
accessTokenUrl,
|
|
clientSecret: templateVariable(variableNames.clientSecret),
|
|
username: "",
|
|
password: "",
|
|
}
|
|
: {
|
|
accessTokenUrl,
|
|
clientSecret: templateVariable(variableNames.clientSecret),
|
|
};
|
|
|
|
return {
|
|
authenticationType: "oauth2",
|
|
authentication: {
|
|
grantType,
|
|
clientId: templateVariable(variableNames.clientId),
|
|
headerPrefix: "Bearer",
|
|
...(scope.length > 0 ? { scope } : {}),
|
|
...grantPatch,
|
|
},
|
|
};
|
|
}
|
|
|
|
return null;
|
|
}
|
|
|
|
function resolveOAuthUrl(
|
|
value: string | undefined,
|
|
baseUrl: string,
|
|
useDynamicServerUrls: boolean,
|
|
): string | undefined {
|
|
if (value == null) return undefined;
|
|
try {
|
|
return new URL(value).toString();
|
|
} catch {
|
|
// Relative endpoint; resolve it against the API base below.
|
|
}
|
|
|
|
if (value.startsWith("//")) return value;
|
|
if (useDynamicServerUrls) {
|
|
return value.startsWith("/")
|
|
? `${templateVariable("baseUrlOrigin")}${value}`
|
|
: joinUrlParts(templateVariable("baseUrl"), value);
|
|
}
|
|
|
|
if (baseUrl.length > 0) {
|
|
try {
|
|
return new URL(value, `${trimTrailingSlashes(baseUrl)}/`).toString();
|
|
} catch {
|
|
// A path-only server has no origin to resolve against. Preserve whether
|
|
// the OAuth endpoint is relative to that path or to the eventual origin.
|
|
}
|
|
}
|
|
|
|
try {
|
|
const placeholderOrigin = "https://openapi-import.invalid";
|
|
const relativeBase = new URL(`${trimTrailingSlashes(baseUrl)}/`, placeholderOrigin);
|
|
const resolved = new URL(value, relativeBase);
|
|
return `${templateVariable("baseUrlOrigin")}${resolved.pathname}${resolved.search}${resolved.hash}`;
|
|
} catch {
|
|
return joinUrlParts(templateVariable("baseUrlOrigin"), value);
|
|
}
|
|
}
|
|
|
|
function buildOAuthVariablesByScheme(
|
|
importState: ImportState,
|
|
spec: UnknownRecord,
|
|
): Map<string, OAuthVariableNames> {
|
|
const schemes = {
|
|
...toRecord(toRecord(spec.components).securitySchemes),
|
|
...toRecord(spec.securityDefinitions),
|
|
};
|
|
const oauthSchemeNames = Object.entries(schemes)
|
|
.filter(([, scheme]) => stringAt(importState.resolve(scheme), "type") === "oauth2")
|
|
.map(([name]) => name);
|
|
const usedPrefixes = new Set<string>();
|
|
|
|
return new Map(
|
|
oauthSchemeNames.map((schemeName) => {
|
|
const basePrefix =
|
|
oauthSchemeNames.length === 1
|
|
? "oauth"
|
|
: `oauth_${schemeName.replaceAll(/[^a-zA-Z0-9_]+/g, "_").replaceAll(/^_+|_+$/g, "") || "auth"}`;
|
|
let prefix = basePrefix;
|
|
let suffix = 2;
|
|
while (usedPrefixes.has(prefix)) prefix = `${basePrefix}_${suffix++}`;
|
|
usedPrefixes.add(prefix);
|
|
return [
|
|
schemeName,
|
|
{ clientId: `${prefix}_client_id`, clientSecret: `${prefix}_client_secret` },
|
|
];
|
|
}),
|
|
);
|
|
}
|
|
|
|
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);
|
|
}
|
|
|
|
/**
|
|
* `examples` is a map of (possibly `$ref`) Example objects on media types and
|
|
* parameters, but a plain array of values on OpenAPI 3.1 schemas.
|
|
*/
|
|
function firstExampleValue(examples: unknown, importState: ImportState): unknown {
|
|
if (Array.isArray(examples)) return examples[0];
|
|
const firstExample = importState.resolve(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 !== "";
|
|
}
|
|
|
|
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) =>
|
|
Array.isArray(current) ? current[Number(part)] : toRecord(current)[part],
|
|
this.#spec,
|
|
);
|
|
|
|
return this.resolve(resolved, nextVisitedRefs);
|
|
}
|
|
}
|