@gitbook/react-openapi 1.5.1 → 1.5.3

package/dist/translations/zh.js

@@ -0,0 +1,50 @@
+//#region src/translations/zh.ts
+const zh = {
+	required: "必填",
+	deprecated: "已弃用",
+	deprecated_and_sunset_on: "此操作已弃用，将于 ${1} 停止使用。",
+	stability_experimental: "实验性",
+	stability_alpha: "Alpha",
+	stability_beta: "Beta",
+	discriminator: "判别器",
+	copy_to_clipboard: "复制到剪贴板",
+	copied: "已复制",
+	no_content: "无内容",
+	unresolved_reference: "未解析的引用",
+	circular_reference: "循环引用",
+	read_only: "只读",
+	write_only: "只写",
+	optional: "可选",
+	min: "最小值",
+	max: "最大值",
+	nullable: "可为 null",
+	body: "请求体",
+	payload: "有效载荷",
+	headers: "头字段",
+	header: "头部",
+	authorizations: "授权",
+	responses: "响应",
+	response: "响应",
+	path_parameters: "路径参数",
+	query_parameters: "查询参数",
+	header_parameters: "头参数",
+	attributes: "属性",
+	test_it: "测试一下",
+	information: "信息",
+	success: "成功",
+	redirect: "重定向",
+	error: "错误",
+	show: "显示${1}",
+	hide: "隐藏${1}",
+	available_items: "可用项",
+	required_scopes: "必需范围",
+	required_scopes_description: "此端点需要以下范围：",
+	available_scopes: "可用范围：",
+	properties: "属性",
+	or: "或",
+	and: "和",
+	possible_values: "可能的值"
+};
+
+//#endregion
+export { zh };

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+import { OpenAPICustomOperationProperties, OpenAPICustomPrefillProperties, OpenAPICustomSpecProperties, OpenAPIV3 } from "@gitbook/openapi-parser";
+
+//#region src/types.d.ts
+type OpenAPIServerVariableWithCustomProperties = OpenAPIV3.ServerVariableObject & OpenAPICustomPrefillProperties;
+/**
+ * OpenAPI ServerObject type extended to provide x-gitbook prefill custom properties at the variable level.
+ */
+type OpenAPIServerWithCustomProperties = Omit<OpenAPIV3.ServerObject, 'variables'> & {
+  name?: string;
+  variables?: {
+    [variable: string]: OpenAPIServerVariableWithCustomProperties;
+  };
+} & OpenAPICustomPrefillProperties;
+type OpenAPISecurityScope = [string, string | undefined];
+type OpenAPICustomSecurityScheme = OpenAPIV3.SecuritySchemeObject & OpenAPICustomPrefillProperties & {
+  required?: boolean;
+  scopes?: OpenAPISecurityScope[] | null;
+};
+interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
+  path: string;
+  method: string;
+  /** Servers to be used for this operation */
+  servers: OpenAPIServerWithCustomProperties[];
+  /** Spec of the operation */
+  operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
+  /** Securities that should be used for this operation */
+  securities: [string, OpenAPICustomSecurityScheme][];
+}
+interface OpenAPIWebhookData extends OpenAPICustomSpecProperties {
+  name: string;
+  method: string;
+  /** Servers to be used for this operation */
+  servers: OpenAPIV3.ServerObject[];
+  /** Spec of the webhook */
+  operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
+}
+//#endregion
+export { OpenAPIOperationData, OpenAPIWebhookData };

package/dist/util/example.js

@@ -0,0 +1,84 @@
+import { tString } from "../translate.js";
+import { OpenAPIExample } from "../OpenAPIExample.js";
+import { checkIsReference } from "../utils.js";
+import { generateSchemaExample } from "../generateSchemaExample.js";
+
+//#region src/util/example.tsx
+/**
+* Generate an example from a reference object.
+*/
+function getExampleFromReference(ref, context) {
+	return {
+		summary: tString(context.translation, "unresolved_reference"),
+		value: { $ref: ref.$ref }
+	};
+}
+/**
+* Get examples from a media type object.
+*/
+function getExamplesFromMediaTypeObject(args) {
+	const { mediaTypeObject, mediaType, context } = args;
+	if (mediaTypeObject.examples) return Object.entries(mediaTypeObject.examples).map(([key, example]) => {
+		return {
+			key,
+			example: checkIsReference(example) ? getExampleFromReference(example, context) : example
+		};
+	});
+	if (mediaTypeObject.example) return [{
+		key: "default",
+		example: { value: mediaTypeObject.example }
+	}];
+	if (mediaTypeObject.schema) {
+		if (mediaType === "application/xml") return [{
+			key: "default",
+			example: { value: { [mediaTypeObject.schema.xml?.name ?? "object"]: generateSchemaExample(mediaTypeObject.schema, {
+				xml: mediaType === "application/xml",
+				mode: "read"
+			}) } }
+		}];
+		return [{
+			key: "default",
+			example: { value: generateSchemaExample(mediaTypeObject.schema, { mode: "read" }) }
+		}];
+	}
+	return [];
+}
+/**
+* Get example from a schema object.
+*/
+function getExampleFromSchema(args) {
+	const { schema } = args;
+	if (schema.example) return { value: schema.example };
+	return { value: generateSchemaExample(schema, { mode: "read" }) };
+}
+/**
+* Get the examples from a media type object.
+*/
+function getExamples(props) {
+	const { mediaTypeObject, mediaType, context } = props;
+	const examples = getExamplesFromMediaTypeObject({
+		mediaTypeObject,
+		mediaType,
+		context
+	});
+	const syntax = getSyntaxFromMediaType(mediaType);
+	return examples.map((example) => {
+		return {
+			key: example.key,
+			label: example.example.summary || example.key,
+			body: <OpenAPIExample example={example.example} context={props.context} syntax={syntax} />
+		};
+	});
+}
+/**
+* Get the syntax from a media type.
+*/
+function getSyntaxFromMediaType(mediaType) {
+	if (mediaType.includes("json")) return "json";
+	if (mediaType.includes("yaml")) return "yaml";
+	if (mediaType === "application/xml") return "xml";
+	return "text";
+}
+
+//#endregion
+export { getExampleFromReference, getExampleFromSchema, getExamples };

package/dist/util/server.js

@@ -0,0 +1,38 @@
+//#region src/util/server.ts
+/**
+* Get the default URL for the server.
+*/
+function getDefaultServerURL(servers) {
+	const server = servers[0];
+	if (!server) return "";
+	return interpolateServerURL(server);
+}
+/**
+* Interpolate the server URL with the default values of the variables.
+*/
+function interpolateServerURL(server) {
+	return parseServerURL(server?.url ?? "").map((part) => {
+		if (part.kind === "text") return part.text;
+		return server.variables?.[part.name]?.default ?? `{${part.name}}`;
+	}).join("");
+}
+function parseServerURL(url) {
+	const parts = url.split(/{([^}]+)}/g);
+	const result = [];
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		if (!part) continue;
+		if (i % 2 === 0) result.push({
+			kind: "text",
+			text: part
+		});
+		else result.push({
+			kind: "variable",
+			name: part
+		});
+	}
+	return result;
+}
+
+//#endregion
+export { getDefaultServerURL };

package/dist/util/tryit-prefill.js

@@ -0,0 +1,143 @@
+import { ExpressionRuntime, parseTemplate } from "@gitbook/expr";
+
+//#region src/util/tryit-prefill.ts
+const PREFILL_CUSTOM_PROPERTY = "x-gitbook-prefill";
+/**
+* Resolve the Scalar API client prefill configuration for a given OpenAPI operation.
+*/
+function resolveTryItPrefillForOperation(args) {
+	const { operation: { securities, servers }, prefillInputContext } = args;
+	if (!prefillInputContext) return {};
+	const runtime = new ExpressionRuntime();
+	const resolveTryItPrefillExpression = (expr) => {
+		if (!parseTemplate(expr).length) return;
+		return runtime.evaluateTemplate(expr, prefillInputContext);
+	};
+	const prefillAuth = securities ? resolveTryItPrefillAuthForOperationSecurities({
+		securities,
+		resolveTryItPrefillExpression
+	}) : void 0;
+	const prefillServers = servers ? resolveTryItPrefillServersForOperationServers({
+		servers,
+		resolveTryItPrefillExpression
+	}) : [];
+	return {
+		...prefillAuth ? { authentication: prefillAuth } : {},
+		...prefillServers ? { servers: prefillServers } : {}
+	};
+}
+/**
+* Resolve prefill authentication configuration for the security schemes defined for an operation.
+*/
+function resolveTryItPrefillAuthForOperationSecurities(args) {
+	const { securities, resolveTryItPrefillExpression } = args;
+	const prefillAuthConfig = {};
+	for (const [schemeName, security] of Object.values(securities)) {
+		const tryitPrefillAuthValue = security[PREFILL_CUSTOM_PROPERTY] ? resolveTryItPrefillExpression(security[PREFILL_CUSTOM_PROPERTY]) : void 0;
+		if (!tryitPrefillAuthValue) continue;
+		switch (security.type) {
+			case "http":
+				if (security.scheme?.includes("bearer")) prefillAuthConfig[schemeName] = { token: tryitPrefillAuthValue };
+				else if (security.scheme?.includes("basic") && tryitPrefillAuthValue.includes(":")) {
+					const [username, password] = tryitPrefillAuthValue.split(":", 2);
+					prefillAuthConfig[schemeName] = {
+						username,
+						password
+					};
+				}
+				break;
+			case "apiKey":
+				prefillAuthConfig[schemeName] = {
+					name: security.name,
+					in: security.in,
+					value: tryitPrefillAuthValue
+				};
+				break;
+			case "oauth2":
+			case "openIdConnect": break;
+		}
+	}
+	return Object.keys(prefillAuthConfig).length > 0 ? { securitySchemes: prefillAuthConfig } : void 0;
+}
+/**
+* Resolve prefill server configuration for the servers defined for an operation.
+*/
+function resolveTryItPrefillServersForOperationServers(args) {
+	const { servers, resolveTryItPrefillExpression } = args;
+	const resolvedServers = [];
+	for (const server of servers) {
+		const tryItPrefillServerUrlExpr = server[PREFILL_CUSTOM_PROPERTY];
+		const tryItPrefillServerUrlValue = tryItPrefillServerUrlExpr ? resolveTryItPrefillExpression(tryItPrefillServerUrlExpr) : void 0;
+		const variables = server.variables ? { ...server.variables } : {};
+		if (server.variables) for (const [varName, variable] of Object.entries(server.variables)) {
+			const { [PREFILL_CUSTOM_PROPERTY]: tryItPrefillVarExpr,...variableProps } = variable;
+			const tryItPrefillVarValue = tryItPrefillVarExpr ? resolveTryItPrefillExpression(tryItPrefillVarExpr) : void 0;
+			variables[varName] = {
+				...variableProps,
+				...tryItPrefillVarValue ? { default: String(tryItPrefillVarValue) } : {}
+			};
+		}
+		const hasServerVariables = Object.keys(variables).length > 0;
+		if (server.url && (tryItPrefillServerUrlValue || hasServerVariables)) {
+			const resolvedServer = {
+				url: tryItPrefillServerUrlValue ?? server.url,
+				...server.description ? { description: server.description } : {},
+				...hasServerVariables ? { variables } : {}
+			};
+			resolvedServers.push(resolvedServer);
+		}
+	}
+	return resolvedServers.length > 0 ? resolvedServers : void 0;
+}
+/**
+* Return a X-GITBOOK-PREFILL placeholder based on the prefill custom property in the provided security scheme.
+*/
+function resolvePrefillCodePlaceholderFromSecurityScheme(args) {
+	const { security, defaultPlaceholderValue } = args;
+	const prefillExprParts = extractPrefillExpressionPartsFromSecurityScheme(security);
+	if (prefillExprParts.length === 0) return defaultPlaceholderValue ?? "";
+	return toPrefillCodePlaceholder(templatePartsToExpression(prefillExprParts), defaultPlaceholderValue);
+}
+function extractPrefillExpressionPartsFromSecurityScheme(security) {
+	const expression = security[PREFILL_CUSTOM_PROPERTY];
+	if (!expression || expression.length === 0) return [];
+	return parseTemplate(expression);
+}
+/**
+* Return a server URL with X-GITBOOK-PREFILL placeholders based on the prefill custom properties in the provided security scheme.
+*/
+function resolveURLWithPrefillCodePlaceholdersFromServer(server, defaultServerUrl) {
+	const serverVariables = server.variables ?? {};
+	const variableExprs = {};
+	let hasVariablePrefill = false;
+	for (const [name, variable] of Object.entries(serverVariables ?? {})) if (variable[PREFILL_CUSTOM_PROPERTY]) {
+		hasVariablePrefill = true;
+		variableExprs[name] = `(${templatePartsToExpression(parseTemplate(variable[PREFILL_CUSTOM_PROPERTY]))} ?? '${variable.default ?? ""}')`;
+	} else variableExprs[name] = String(variable.default) ?? "";
+	let interpolatedUrl = server.url ?? "";
+	interpolatedUrl = interpolatedUrl.replace(/{([^}]+)}/g, (_, varName) => {
+		const expr = variableExprs[varName];
+		if (serverVariables[varName]?.[PREFILL_CUSTOM_PROPERTY]) return `\${${expr ?? `'${varName}'`}}`;
+		return expr ?? `{${varName}}`;
+	});
+	const interpolatedUrlTemplate = hasVariablePrefill ? `\`${interpolatedUrl}\`` : interpolatedUrl;
+	const urlLevelExpr = server[PREFILL_CUSTOM_PROPERTY];
+	if (urlLevelExpr) return toPrefillCodePlaceholder(`${templatePartsToExpression(parseTemplate(urlLevelExpr))} ?? ${hasVariablePrefill ? interpolatedUrlTemplate : `'${interpolatedUrlTemplate}'`}`, defaultServerUrl);
+	if (hasVariablePrefill) return toPrefillCodePlaceholder(interpolatedUrlTemplate, defaultServerUrl);
+	return interpolatedUrl;
+}
+function templatePartsToExpression(parts) {
+	return parts.map((part) => {
+		switch (part.type) {
+			case "text": return `"${part.value}"`;
+			case "expression": return part.value;
+			default: return "";
+		}
+	}).join(" + ");
+}
+function toPrefillCodePlaceholder(expression, defaultValue) {
+	return `$$__X-GITBOOK-PREFILL[(${expression})${defaultValue ? ` ?? '${defaultValue}'` : ""}]__$$`;
+}
+
+//#endregion
+export { resolvePrefillCodePlaceholderFromSecurityScheme, resolveTryItPrefillForOperation, resolveURLWithPrefillCodePlaceholdersFromServer };

package/dist/utils.js

@@ -0,0 +1,163 @@
+import { stringifyOpenAPI } from "./stringifyOpenAPI.js";
+import { tString } from "./translate.js";
+
+//#region src/utils.ts
+function checkIsReference(input) {
+	return typeof input === "object" && !!input && "$ref" in input;
+}
+function createStateKey(key, scope) {
+	return scope ? `${scope}_${key}` : key;
+}
+/**
+* Check if an object has a description. Either at the root level or in items.
+*/
+function hasDescription(object) {
+	return "description" in object || "x-gitbook-description-html" in object;
+}
+/**
+* Resolve the description of an object.
+*/
+function resolveDescription(object) {
+	if (hasDescription(object)) return "x-gitbook-description-html" in object && typeof object["x-gitbook-description-html"] === "string" ? object["x-gitbook-description-html"].trim() : typeof object.description === "string" ? object.description.trim() : void 0;
+	if ("items" in object && typeof object.items === "object" && hasDescription(object.items)) return resolveDescription(object.items);
+}
+/**
+* Extract descriptions from an object.
+*/
+function extractDescriptions(object) {
+	return {
+		description: object.description,
+		"x-gitbook-description-html": "x-gitbook-description-html" in object ? object["x-gitbook-description-html"] : void 0
+	};
+}
+/**
+* Resolve the first example from an object.
+*/
+function resolveFirstExample(object) {
+	if ("examples" in object && typeof object.examples === "object" && object.examples) {
+		const firstKey = Object.keys(object.examples)[0];
+		if (firstKey && object.examples[firstKey]) return formatExample(object.examples[firstKey]);
+	}
+	if (shouldDisplayExample(object)) return formatExample(object.example);
+	if (object.items && typeof object.items === "object") return formatExample(object.items.example);
+}
+/**
+* Resolve the schema of a parameter.
+* Extract the description, example and deprecated from parameter.
+*/
+function resolveParameterSchema(parameter) {
+	const schema = checkIsReference(parameter.schema) ? void 0 : parameter.schema;
+	return {
+		...extractDescriptions(parameter),
+		example: resolveFirstExample(parameter),
+		deprecated: parameter.deprecated,
+		...schema
+	};
+}
+/**
+* Transform a parameter object to a property object.
+*/
+function parameterToProperty(parameter) {
+	if (checkIsReference(parameter)) return {
+		propertyName: parameter.$ref ?? "Unknown ref",
+		schema: {},
+		required: void 0
+	};
+	return {
+		propertyName: parameter.name,
+		schema: resolveParameterSchema(parameter),
+		required: parameter.required
+	};
+}
+/**
+* Format the example of a schema.
+*/
+function formatExample(example) {
+	if (typeof example === "string") return example.replace(/\n/g, " ").replace(/\s+/g, " ").replace(/([\{\}:,])\s+/g, "$1 ").replace(/\s+([\{\}:,])/g, " $1").trim();
+	return stringifyOpenAPI(example);
+}
+/**
+* Check if an example should be displayed.
+*/
+function shouldDisplayExample(schema) {
+	return typeof schema.example === "string" && !!schema.example || typeof schema.example === "number" || typeof schema.example === "boolean" || Array.isArray(schema.example) && schema.example.length > 0 || typeof schema.example === "object" && schema.example !== null && Object.keys(schema.example).length > 0;
+}
+/**
+* Get the class name for a status code.
+* 1xx: informational
+* 2xx: success
+* 3xx: redirect
+* 4xx, 5xx: error
+*/
+function getStatusCodeClassName(statusCode) {
+	switch (getStatusCodeCategory(statusCode)) {
+		case 1: return "informational";
+		case 2: return "success";
+		case 3: return "redirect";
+		case 4:
+		case 5: return "error";
+		default: return "unknown";
+	}
+}
+/**
+* Get a default label for a status code.
+* This is used when there is no label provided in the OpenAPI spec.
+* 1xx: Information
+* 2xx: Success
+* 3xx: Redirect
+* 4xx, 5xx: Error
+*/
+function getStatusCodeDefaultLabel(statusCode, context) {
+	switch (getStatusCodeCategory(statusCode)) {
+		case 1: return tString(context.translation, "information");
+		case 2: return tString(context.translation, "success");
+		case 3: return tString(context.translation, "redirect");
+		case 4:
+		case 5: return tString(context.translation, "error");
+		default: return "";
+	}
+}
+function getStatusCodeCategory(statusCode) {
+	const code = typeof statusCode === "string" ? Number.parseInt(statusCode, 10) : statusCode;
+	if (Number.isNaN(code) || code < 100 || code >= 600) return "unknown";
+	return Math.floor(code / 100);
+}
+function getSchemaTitle(schema) {
+	let type = "any";
+	if (schema.enum || schema["x-enumDescriptions"] || schema["x-gitbook-enum"]) type = `${schema.type} · enum`;
+	else if (schema.type === "array" && !!schema.items) type = `${getSchemaTitle(schema.items)}[]`;
+	else if (Array.isArray(schema.type)) type = schema.type.join(" | ");
+	else if (schema.type || schema.properties) {
+		type = schema.type ?? "object";
+		if (schema.format) type += ` · ${schema.format}`;
+		if (type === "object" && schema.title) type += ` · ${schema.title.replaceAll(" ", "")}`;
+	}
+	if ("anyOf" in schema) type = "any of";
+	else if ("oneOf" in schema) type = "one of";
+	else if ("allOf" in schema) type = "all of";
+	else if ("not" in schema) type = "not";
+	return type;
+}
+/**
+* Extract security information for an operation based on its security requirements and the spec security schemes.
+*/
+function extractOperationSecurityInfo(args) {
+	const { securityRequirement, securities } = args;
+	const securitiesMap = new Map(securities);
+	if (!securityRequirement || securityRequirement.length === 0) return securities.map(([key, security]) => ({
+		key,
+		label: key,
+		schemes: [security]
+	}));
+	return securityRequirement.map((requirement, idx) => {
+		const schemeKeys = Object.keys(requirement);
+		return {
+			key: `security-${idx}`,
+			label: schemeKeys.join(" & "),
+			schemes: schemeKeys.map((schemeKey) => securitiesMap.get(schemeKey)).filter((s) => s !== void 0)
+		};
+	});
+}
+
+//#endregion
+export { checkIsReference, createStateKey, extractOperationSecurityInfo, getSchemaTitle, getStatusCodeClassName, getStatusCodeDefaultLabel, parameterToProperty, resolveDescription, resolveFirstExample };

package/package.json

@@ -7,42 +7,58 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.5.1",
+    "version": "1.5.3",
     "sideEffects": false,
     "dependencies": {
-        "@gitbook/expr": "1.2.2",
-        "@gitbook/openapi-parser": "3.0.3",
-        "@scalar/api-client-react": "^1.3.16",
-        "@scalar/oas-utils": "^0.2.130",
-        "@scalar/types": "^0.1.9",
-        "clsx": "^2.1.1",
+        "@gitbook/expr": "1.2.4",
+        "@gitbook/openapi-parser": "3.0.5",
+        "@scalar/api-client-react": "^1.3.46",
+        "@scalar/oas-utils": "^0.6.3",
+        "@scalar/types": "^0.4.0",
+        "classnames": "^2.5.1",
         "flatted": "^3.2.9",
         "json-xml-parse": "^1.3.0",
-        "react-aria-components": "^1.6.0",
-        "react-aria": "^3.37.0",
-        "usehooks-ts": "^3.1.0",
+        "react-aria-components": "^1.13.0",
+        "react-aria": "^3.44.0",
+        "react-stately": "^3.42.0",
+        "usehooks-ts": "^3.1.1",
         "zustand": "^5.0.3",
         "js-yaml": "^4.1.0"
     },
     "devDependencies": {
         "@types/js-yaml": "^4.0.9",
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
         "bun-types": "^1.1.20",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0",
         "tsdown": "^0.15.6",
         "typescript": "^5.5.3"
     },
+    "overrides": {
+        "@types/react": "catalog:",
+        "@types/react-dom": "catalog:",
+        "react": "catalog:",
+        "react-dom": "catalog:"
+    },
     "peerDependencies": {
-        "react": "*"
+        "react": "*",
+        "react-dom": "*"
     },
     "scripts": {
         "build": "tsdown",
         "typecheck": "tsc --noEmit",
         "unit": "bun test",
         "dev": "bun run build -- --watch ./src",
-        "clean": "rm -rf ./dist"
+        "clean": "rm -rf ./dist",
+        "publish-to-npm": "../../scripts/publish-if-new.sh"
     },
     "files": ["dist", "README.md", "CHANGELOG.md"],
     "publishConfig": {
         "access": "public",
         "registry": "https://registry.npmjs.org/"
+    },
+    "repository": {
+        "url": "https://github.com/GitbookIO/gitbook"
     }
 }