@scalar/oas-utils 0.10.8 → 0.10.10

package/dist/spec-getters/get-parameters-from-operation.js

@@ -1,24 +1,40 @@
-import { getExampleFromSchema } from "./get-example-from-schema.js";
-function getParametersFromOperation(operationParameters = [], pathParameters = [], where, requiredOnly = true) {
-  const parameters = [...pathParameters || [], ...operationParameters || []];
-  const params = parameters.filter((parameter) => parameter.in === where).filter((parameter) => requiredOnly && parameter.required || !requiredOnly).map((parameter) => ({
-    name: parameter.name ?? "Unknown Parameter",
-    description: parameter.description ?? null,
-    value: parameter.example ? parameter.example : parameter.schema ? getExampleFromSchema(parameter.schema, { mode: "write" }) : "",
-    required: parameter.required ?? false,
-    enabled: parameter.required ?? false
-  }));
-  return params.sort((a, b) => {
-    if (a.required && !b.required) {
-      return -1;
-    }
-    if (!a.required && b.required) {
-      return 1;
-    }
-    return 0;
-  });
+import { getExampleFromSchema } from './get-example-from-schema.js';
+/**
+ * Get the query parameters from an operation.
+ *
+ * Example: [ { name: 'foobar', value: '' } ]
+ *
+ * - OpenAPI 3.x: Possible values are "query", "header", "path" or "cookie".
+ */
+export function getParametersFromOperation(operationParameters = [], pathParameters = [], where, requiredOnly = true) {
+    const parameters = [...(pathParameters || []), ...(operationParameters || [])];
+    const params = parameters
+        // query, path, header, cookie?
+        .filter((parameter) => parameter.in === where)
+        // don't add optional parameters
+        .filter((parameter) => (requiredOnly && parameter.required) || !requiredOnly)
+        // transform them
+        .map((parameter) => ({
+        name: parameter.name ?? 'Unknown Parameter',
+        description: parameter.description ?? null,
+        value: parameter.example
+            ? parameter.example
+            : parameter.schema
+                ? getExampleFromSchema(parameter.schema, { mode: 'write' })
+                : '',
+        required: parameter.required ?? false,
+        enabled: parameter.required ?? false,
+    }));
+    return params.sort((a, b) => {
+        // Move a up if a is required and b is not
+        if (a.required && !b.required) {
+            return -1;
+        }
+        // Move b up if b is required and a is not
+        if (!a.required && b.required) {
+            return 1;
+        }
+        // Keep original order if both have the same required status
+        return 0;
+    });
 }
-export {
-  getParametersFromOperation
-};
-//# sourceMappingURL=get-parameters-from-operation.js.map

package/dist/spec-getters/get-request-body-from-operation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-request-body-from-operation.d.ts","sourceRoot":"","sources":["../../src/spec-getters/get-request-body-from-operation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAGvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AA6ChD;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,aAAa,GAAG,YAAY,CAAC,EACxD,kBAAkB,CAAC,EAAE,MAAM,GAAG,MAAM,EACpC,8BAA8B,CAAC,EAAE,OAAO,GACvC;IACD,QAAQ,EAAE,WAAW,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,MAAM,CAAA;QACZ,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KACtB,EAAE,CAAA;CACJ,GAAG,IAAI,CA2KP"}
+{"version":3,"file":"get-request-body-from-operation.d.ts","sourceRoot":"","sources":["../../src/spec-getters/get-request-body-from-operation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAGvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AA6ChD;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,aAAa,GAAG,YAAY,CAAC,EACxD,kBAAkB,CAAC,EAAE,MAAM,GAAG,MAAM,EACpC,8BAA8B,CAAC,EAAE,OAAO,GACvC;IACD,QAAQ,EAAE,WAAW,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,MAAM,CAAA;QACZ,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KACtB,EAAE,CAAA;CACJ,GAAG,IAAI,CA2KP"}

package/dist/spec-getters/get-request-body-from-operation.js

@@ -1,134 +1,176 @@
-import { json2xml } from "@scalar/helpers/file/json2xml";
-import { getResolvedRef } from "@scalar/workspace-store/helpers/get-resolved-ref";
-import { normalizeMimeTypeObject } from "../helpers/normalize-mime-type-object.js";
-import { prettyPrintJson } from "../helpers/pretty-print-json.js";
-import { getExampleFromSchema } from "./get-example-from-schema.js";
-import { getParametersFromOperation } from "./get-parameters-from-operation.js";
+import { json2xml } from '@scalar/helpers/file/json2xml';
+import { prettyPrintJson } from '@scalar/helpers/json/pretty-print-json';
+import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
+import { normalizeMimeTypeObject } from '../helpers/normalize-mime-type-object.js';
+import { getExampleFromSchema } from './get-example-from-schema.js';
+import { getParametersFromOperation } from './get-parameters-from-operation.js';
+/**
+ * Transform the object into a nested array of objects
+ * that represent the key-value pairs of the object.
+ */
 function getParamsFromObject(obj, nested = false, field) {
-  return Object.entries(obj).flatMap(([key, value]) => {
-    const name = field ?? key;
-    if (Array.isArray(value) && !nested) {
-      return getParamsFromObject(value, true, key);
-    }
-    if (typeof value === "object" && !(value instanceof File) && value !== null) {
-      value = JSON.stringify(value);
-    }
-    return [{ name, value }];
-  });
+    return Object.entries(obj).flatMap(([key, value]) => {
+        const name = field ?? key;
+        if (Array.isArray(value) && !nested) {
+            return getParamsFromObject(value, true, key);
+        }
+        if (typeof value === 'object' && !(value instanceof File) && value !== null) {
+            // Nested object inside formData field: no way to represent it, so just serialize to JSON string
+            value = JSON.stringify(value);
+        }
+        return [{ name, value }];
+    });
 }
+// Define preferred standard mime types (order indicates preference)
 const standardMimeTypes = [
-  "application/json",
-  "application/octet-stream",
-  "application/x-www-form-urlencoded",
-  "application/xml",
-  "multipart/form-data",
-  "text/plain"
+    'application/json',
+    'application/octet-stream',
+    'application/x-www-form-urlencoded',
+    'application/xml',
+    'multipart/form-data',
+    'text/plain',
 ];
-function getRequestBodyFromOperation(operation, selectedExampleKey, omitEmptyAndOptionalProperties) {
-  const originalContent = operation.requestBody?.content;
-  const content = normalizeMimeTypeObject(originalContent);
-  const mimeType = standardMimeTypes.find((currentMimeType) => !!content?.[currentMimeType]) ?? (Object.keys(content ?? {})[0] || "application/json");
-  const isJsonLike = mimeType.includes("json") || mimeType.endsWith("+json");
-  const examples = content?.[mimeType]?.examples ?? content?.["application/json"]?.examples;
-  const selectedExample = examples?.[selectedExampleKey ?? Object.keys(examples ?? {})[0] ?? ""];
-  if (selectedExample) {
-    return {
-      mimeType,
-      text: prettyPrintJson("value" in selectedExample ? selectedExample.value : selectedExample)
-    };
-  }
-  const bodyParameters = getParametersFromOperation(
-    operation.parameters ?? [],
+/**
+ * Get the request body from the operation.
+ */
+export function getRequestBodyFromOperation(operation, selectedExampleKey, omitEmptyAndOptionalProperties) {
+    const originalContent = operation.requestBody?.content;
+    const content = normalizeMimeTypeObject(originalContent);
+    // First try to find a standard mime type
+    const mimeType = standardMimeTypes.find((currentMimeType) => !!content?.[currentMimeType]) ??
+        (Object.keys(content ?? {})[0] || 'application/json');
+    // Handle JSON-like content types (e.g., application/vnd.github+json)
+    const isJsonLike = mimeType.includes('json') || mimeType.endsWith('+json');
+    /** Examples */
+    const examples = content?.[mimeType]?.examples ?? content?.['application/json']?.examples;
+    // Let's use the first example
+    const selectedExample = examples?.[selectedExampleKey ?? Object.keys(examples ?? {})[0] ?? ''];
+    if (selectedExample) {
+        return {
+            mimeType,
+            text: prettyPrintJson('value' in selectedExample ? selectedExample.value : selectedExample),
+        };
+    }
+    /**
+     * Body Parameters (Swagger 2.0)
+     *
+     * ”The payload that's appended to the HTTP request. Since there can only be one payload, there can only
+     * be one body parameter. The name of the body parameter has no effect on the parameter itself and is used
+     * for documentation purposes only. Since Form parameters are also in the payload, body and form
+     * parameters cannot exist together for the same operation.”
+     */
+    const bodyParameters = getParametersFromOperation(operation.parameters ?? [], 
     // TODO: Add path parameters
-    [],
-    // operation.path ?? [],
-    "body",
-    false
-  );
-  if (bodyParameters.length > 0) {
-    return {
-      mimeType: "application/json",
-      text: prettyPrintJson(bodyParameters[0]?.value ?? "")
-    };
-  }
-  const formDataParameters = getParametersFromOperation(
-    operation.parameters ?? [],
+    [], // operation.path ?? [],
+    'body', false);
+    if (bodyParameters.length > 0) {
+        return {
+            mimeType: 'application/json',
+            text: prettyPrintJson(bodyParameters[0]?.value ?? ''),
+        };
+    }
+    /**
+     * FormData Parameters (Swagger 2.0)
+     *
+     * ”Form - Used to describe the payload of an HTTP request when either application/x-www-form-urlencoded,
+     * multipart/form-data or both are used as the content type of the request (in Swagger's definition, the
+     * consumes property of an operation). This is the only parameter type that can be used to send files,
+     * thus supporting the file type. Since form parameters are sent in the payload, they cannot be declared
+     * together with a body parameter for the same operation. Form parameters have a different format based on
+     * the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
+     * - application/x-www-form-urlencoded - Similar to the format of Query parameters but as a payload.
+     *   For example, foo=1&bar=swagger - both foo and bar are form parameters. This is normally used for simple
+     *   parameters that are being transferred.
+     * - multipart/form-data - each parameter takes a section in the payload with an internal header.
+     *   For example, for the header Content-Disposition: form-data; name="submit-name" the name of the parameter is
+     *   submit-name. This type of form parameters is more commonly used for file transfers.”
+     */
+    const formDataParameters = getParametersFromOperation(operation.parameters ?? [], 
     // TODO: Add path parameters
-    [],
-    // operation.path ?? [],
-    "formData",
-    false
-  );
-  if (formDataParameters.length > 0) {
-    return {
-      mimeType: "application/x-www-form-urlencoded",
-      params: formDataParameters.map((parameter) => ({
-        name: parameter.name,
-        /**
-         * TODO: This value MUST be a string
-         * Figure out why this is not always a string
-         *
-         * JSON.stringify is a TEMPORARY fix
-         */
-        value: typeof parameter.value === "string" ? parameter.value : JSON.stringify(parameter.value)
-      }))
-    };
-  }
-  if (!mimeType) {
+    [], // operation.path ?? [],
+    'formData', false);
+    if (formDataParameters.length > 0) {
+        return {
+            mimeType: 'application/x-www-form-urlencoded',
+            params: formDataParameters.map((parameter) => ({
+                name: parameter.name,
+                /**
+                 * TODO: This value MUST be a string
+                 * Figure out why this is not always a string
+                 *
+                 * JSON.stringify is a TEMPORARY fix
+                 */
+                value: typeof parameter.value === 'string' ? parameter.value : JSON.stringify(parameter.value),
+            })),
+        };
+    }
+    // If no mime type is supported, exit early
+    if (!mimeType) {
+        return null;
+    }
+    // Get the request body object for the mime type
+    const requestBodyObject = content?.[mimeType];
+    // Get example from operation
+    const example = requestBodyObject?.example ? requestBodyObject?.example : undefined;
+    // Update the JSON handling section
+    if (isJsonLike) {
+        const exampleFromSchema = requestBodyObject?.schema
+            ? getExampleFromSchema(getResolvedRef(requestBodyObject?.schema), {
+                mode: 'write',
+                omitEmptyAndOptionalProperties: omitEmptyAndOptionalProperties ?? false,
+            })
+            : null;
+        const body = example ?? exampleFromSchema;
+        return {
+            mimeType,
+            text: body ? (typeof body === 'string' ? body : JSON.stringify(body, null, 2)) : undefined,
+        };
+    }
+    // XML
+    if (mimeType === 'application/xml') {
+        const exampleFromSchema = requestBodyObject?.schema
+            ? getExampleFromSchema(getResolvedRef(requestBodyObject?.schema), {
+                xml: true,
+                mode: 'write',
+            })
+            : null;
+        return {
+            mimeType,
+            text: example ?? json2xml(exampleFromSchema),
+        };
+    }
+    // Binary data
+    if (mimeType === 'application/octet-stream') {
+        return {
+            mimeType,
+            text: 'BINARY',
+        };
+    }
+    // Plain text
+    if (mimeType === 'text/plain') {
+        const exampleFromSchema = requestBodyObject?.schema
+            ? getExampleFromSchema(getResolvedRef(requestBodyObject?.schema), {
+                xml: true,
+                mode: 'write',
+            })
+            : null;
+        return {
+            mimeType,
+            text: example ?? exampleFromSchema ?? '',
+        };
+    }
+    // URL encoded data
+    if (mimeType === 'multipart/form-data' || mimeType === 'application/x-www-form-urlencoded') {
+        const exampleFromSchema = requestBodyObject?.schema
+            ? getExampleFromSchema(getResolvedRef(requestBodyObject?.schema), {
+                xml: true,
+                mode: 'write',
+            })
+            : null;
+        return {
+            mimeType,
+            params: getParamsFromObject(example ?? exampleFromSchema ?? {}),
+        };
+    }
     return null;
-  }
-  const requestBodyObject = content?.[mimeType];
-  const example = requestBodyObject?.example ? requestBodyObject?.example : void 0;
-  if (isJsonLike) {
-    const exampleFromSchema = requestBodyObject?.schema ? getExampleFromSchema(getResolvedRef(requestBodyObject?.schema), {
-      mode: "write",
-      omitEmptyAndOptionalProperties: omitEmptyAndOptionalProperties ?? false
-    }) : null;
-    const body = example ?? exampleFromSchema;
-    return {
-      mimeType,
-      text: body ? typeof body === "string" ? body : JSON.stringify(body, null, 2) : void 0
-    };
-  }
-  if (mimeType === "application/xml") {
-    const exampleFromSchema = requestBodyObject?.schema ? getExampleFromSchema(getResolvedRef(requestBodyObject?.schema), {
-      xml: true,
-      mode: "write"
-    }) : null;
-    return {
-      mimeType,
-      text: example ?? json2xml(exampleFromSchema)
-    };
-  }
-  if (mimeType === "application/octet-stream") {
-    return {
-      mimeType,
-      text: "BINARY"
-    };
-  }
-  if (mimeType === "text/plain") {
-    const exampleFromSchema = requestBodyObject?.schema ? getExampleFromSchema(getResolvedRef(requestBodyObject?.schema), {
-      xml: true,
-      mode: "write"
-    }) : null;
-    return {
-      mimeType,
-      text: example ?? exampleFromSchema ?? ""
-    };
-  }
-  if (mimeType === "multipart/form-data" || mimeType === "application/x-www-form-urlencoded") {
-    const exampleFromSchema = requestBodyObject?.schema ? getExampleFromSchema(getResolvedRef(requestBodyObject?.schema), {
-      xml: true,
-      mode: "write"
-    }) : null;
-    return {
-      mimeType,
-      params: getParamsFromObject(example ?? exampleFromSchema ?? {})
-    };
-  }
-  return null;
 }
-export {
-  getRequestBodyFromOperation
-};
-//# sourceMappingURL=get-request-body-from-operation.js.map

package/dist/spec-getters/get-server-variable-examples.js

@@ -1,15 +1,12 @@
-const getServerVariableExamples = (server) => {
-  const examples = {};
-  if (server.variables) {
-    for (const [key, variable] of Object.entries(server.variables)) {
-      examples[key] = variable.enum?.filter((v) => typeof v === "string") ?? [
-        variable.default
-      ];
+/** Retrieve example values for server variables */
+export const getServerVariableExamples = (server) => {
+    const examples = {};
+    if (server.variables) {
+        for (const [key, variable] of Object.entries(server.variables)) {
+            examples[key] = variable.enum?.filter((v) => typeof v === 'string') ?? [
+                variable.default,
+            ];
+        }
     }
-  }
-  return examples;
+    return examples;
 };
-export {
-  getServerVariableExamples
-};
-//# sourceMappingURL=get-server-variable-examples.js.map

package/dist/spec-getters/index.js

@@ -1,11 +1,4 @@
-import { getExampleFromSchema } from "./get-example-from-schema.js";
-import { getParametersFromOperation } from "./get-parameters-from-operation.js";
-import { getRequestBodyFromOperation } from "./get-request-body-from-operation.js";
-import { getServerVariableExamples } from "./get-server-variable-examples.js";
-export {
-  getExampleFromSchema,
-  getParametersFromOperation,
-  getRequestBodyFromOperation,
-  getServerVariableExamples
-};
-//# sourceMappingURL=index.js.map
+export { getExampleFromSchema } from './get-example-from-schema.js';
+export { getParametersFromOperation } from './get-parameters-from-operation.js';
+export { getRequestBodyFromOperation } from './get-request-body-from-operation.js';
+export { getServerVariableExamples } from './get-server-variable-examples.js';