swaggie 1.8.1 → 1.8.2

package/dist/gen/genOperations.js

@@ -96,45 +96,63 @@ function prepareClient(
   }
 
   return ops.map((op) => {
-    const [respObject, responseContentType] = _utils.getBestResponse.call(void 0, op, components);
-    const returnType = _swagger.getParameterType.call(void 0, respObject, options);
+    const operationContext = `${op.method.toUpperCase()} ${op.path} (${op.operationId || 'unknown operationId'})`;
 
-    const body = getRequestBody(op.requestBody, components, options);
-    const queryParams = getParams(op.parameters , options, ['query']);
-    const params = getParams(op.parameters , options);
+    try {
+      const [respObject, responseContentType] = _utils.getBestResponse.call(void 0, op, components);
+      const returnType = _swagger.getParameterType.call(void 0, respObject, options);
 
-    if (body) {
-      params.unshift(body);
-    }
+      const body = getRequestBody(op.requestBody, components, options);
+      const queryParams = getParams(op.parameters , options, ['query']);
+      const params = getParams(op.parameters , options);
+
+      if (body) {
+        params.unshift(body);
+      }
 
     // If all parameters have 'x-position' defined, sort them by it
-    if (params.every((p) => p.original['x-position'])) {
-      params.sort((a, b) => a.original['x-position'] - b.original['x-position']);
-    }
+      if (params.every((p) => p.original['x-position'])) {
+        params.sort((a, b) => a.original['x-position'] - b.original['x-position']);
+      }
 
-    markParametersAsSkippable(params);
+      markParametersAsSkippable(params);
 
-    const headers = getParams(op.parameters , options, ['header']);
-    // Some libraries need to know the content type of the request body in case of urlencoded body
-    if (_optionalChain([body, 'optionalAccess', _2 => _2.contentType]) === 'urlencoded') {
-      headers.push({
-        originalName: 'Content-Type',
-        value: 'application/x-www-form-urlencoded',
-      });
-    }
+      const headers = getParams(
+        op.parameters ,
+        options,
+        ['header']
+      );
+      // Some libraries need explicit Content-Type for request bodies.
+      if (_optionalChain([body, 'optionalAccess', _2 => _2.contentType]) === 'urlencoded') {
+        upsertFixedHeader(headers, 'Content-Type', 'application/x-www-form-urlencoded');
+      } else if (_optionalChain([body, 'optionalAccess', _3 => _3.contentType]) === 'json' && options.template === 'fetch') {
+        upsertFixedHeader(headers, 'Content-Type', 'application/json');
+      }
 
-    return {
-      jsDocs: _jsDocs.prepareJsDocsForOperation.call(void 0, op, params),
-      returnType,
-      responseContentType,
-      method: op.method.toUpperCase(),
-      name: getOperationName(op.operationId, op.group),
-      url: prepareUrl(op.path),
-      parameters: params,
-      query: queryParams,
-      body,
-      headers,
-    };
+      return {
+        jsDocs: _jsDocs.prepareJsDocsForOperation.call(void 0, op, params),
+        returnType,
+        responseContentType,
+        method: op.method.toUpperCase(),
+        name: getOperationName(op.operationId, op.group),
+        url: prepareUrl(op.path),
+        parameters: params,
+        query: queryParams,
+        body,
+        headers,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.includes('Invalid schema at')) {
+        throw new Error(
+          `Failed to prepare operation ${operationContext}. ` +
+            'Check if schema is valid for this operation. ' +
+            'Most common culprit is `properties.$ref` (use `schema.$ref` at root, or put `$ref` under a named property).'
+        );
+      }
+
+      throw new Error(`Failed to prepare operation ${operationContext}: ${message}`);
+    }
   });
 } exports.prepareOperations = prepareOperations;
 
@@ -237,10 +255,10 @@ function prepareUrl(path) {
       type: _swagger.getParameterType.call(void 0, p, options),
       optional: p.required === undefined || p.required === null ? true : !p.required,
       original: p,
-      jsDoc: _optionalChain([p, 'access', _3 => _3.description, 'optionalAccess', _4 => _4.trim, 'call', _5 => _5()]),
+      jsDoc: _optionalChain([p, 'access', _4 => _4.description, 'optionalAccess', _5 => _5.trim, 'call', _6 => _6()]),
     }));
 
-  if (_optionalChain([options, 'access', _6 => _6.modifiers, 'optionalAccess', _7 => _7.parameters])) {
+  if (_optionalChain([options, 'access', _7 => _7.modifiers, 'optionalAccess', _8 => _8.parameters])) {
     for (const [name, modifier] of Object.entries(options.modifiers.parameters)) {
       const paramIndex = result.findIndex(
         (p) => p.original.in !== 'path' && (p.originalName === name || p.name === name)
@@ -291,7 +309,7 @@ function getRequestBody(
   let reqBody;
   if ('$ref' in rawReqBody) {
     const refName = rawReqBody.$ref.replace('#/components/requestBodies/', '');
-    const resolved = _optionalChain([components, 'optionalAccess', _8 => _8.requestBodies, 'optionalAccess', _9 => _9[refName]]);
+    const resolved = _optionalChain([components, 'optionalAccess', _9 => _9.requestBodies, 'optionalAccess', _10 => _10[refName]]);
     if (!resolved || '$ref' in resolved) {
       console.error(`RequestBody $ref '${rawReqBody.$ref}' not found in components/requestBodies`);
       return null;
@@ -317,3 +335,19 @@ function getRequestBody(
 
   return null;
 }
+
+function upsertFixedHeader(headers, headerName, value) {
+  const headerIndex = headers.findIndex(
+    (header) => header.originalName.toLowerCase() === headerName.toLowerCase()
+  );
+
+  if (headerIndex >= 0) {
+    headers[headerIndex].value = value;
+    return;
+  }
+
+  headers.push({
+    originalName: headerName,
+    value,
+  });
+}

package/dist/gen/genTypes.js

@@ -61,6 +61,7 @@ function renderSchema(
   }
 
   const result = [];
+  const schemaContext = `components.schemas.${safeName}`;
   if (_nullishCoalesce(schema.description, () => ( schema.title))) {
     result.push(_jsDocs.renderComment.call(void 0, _nullishCoalesce(schema.description, () => ( schema.title))));
   }
@@ -83,8 +84,8 @@ function renderSchema(
   if ('allOf' in schema) {
     const types = _swagger.getRefCompositeTypes.call(void 0, schema);
     const mergedSchema = getMergedCompositeObjects(schema);
-    const objectType = _swagger.getTypeFromSchema.call(void 0, mergedSchema, options);
-    const objectContents = generateObjectTypeContents(mergedSchema, options);
+    const objectType = _swagger.getTypeFromSchema.call(void 0, mergedSchema, options, `${schemaContext}.allOf`);
+    const objectContents = generateObjectTypeContents(mergedSchema, options, schemaContext);
     const hasAdditionalProperties = !!mergedSchema.additionalProperties;
 
     if (hasAdditionalProperties) {
@@ -103,7 +104,7 @@ function renderSchema(
     result.push(`export interface ${safeName} ${extensions}{`);
     result.push(objectContents);
   } else if ('oneOf' in schema || 'anyOf' in schema) {
-    const typeDefinition = _swagger.getTypeFromSchema.call(void 0, schema, options);
+    const typeDefinition = _swagger.getTypeFromSchema.call(void 0, schema, options, schemaContext);
     result.push(`export type ${safeName} = ${typeDefinition};`);
 
     return `${result.join('\n')}\n`;
@@ -113,10 +114,10 @@ function renderSchema(
     result.push(`export type ${safeName} = ${generateItemsType(schema.items, options)}[];`);
     return result.join('\n');
   } else {
-    const objectType = _swagger.getTypeFromSchema.call(void 0, schema, options);
+    const objectType = _swagger.getTypeFromSchema.call(void 0, schema, options, schemaContext);
     const hasAdditionalProperties = !!schema.additionalProperties;
 
-    const objectContents = generateObjectTypeContents(schema, options);
+    const objectContents = generateObjectTypeContents(schema, options, schemaContext);
     if (hasAdditionalProperties) {
       result.push(`export type ${safeName} = ${objectType};`);
       return `${result.join('\n')}\n`;
@@ -138,7 +139,11 @@ function renderSchema(
 /**
  * Generates the inline contents of an object type.
  */
-function generateObjectTypeContents(schema, options) {
+function generateObjectTypeContents(
+  schema,
+  options,
+  schemaContext = 'components.schemas.unknown'
+) {
   const result = [];
   const required = schema.required || [];
   const props = Object.keys(schema.properties || {});
@@ -146,7 +151,7 @@ function generateObjectTypeContents(schema, options) {
   for (const prop of props) {
     const propDefinition = schema.properties[prop];
     const isRequired = !!~required.indexOf(prop);
-    result.push(renderTypeProp(prop, propDefinition, isRequired, options));
+    result.push(renderTypeProp(prop, propDefinition, isRequired, options, schemaContext));
   }
 
   return result.join('\n');
@@ -233,10 +238,11 @@ function renderTypeProp(
   propName,
   definition,
   required,
-  options
+  options,
+  schemaContext
 ) {
   const lines = [];
-  const type = _swagger.getTypeFromSchema.call(void 0, definition, options);
+  const type = _swagger.getTypeFromSchema.call(void 0, definition, options, `${schemaContext}.properties.${propName}`);
 
   if ('description' in definition || 'title' in definition) {
     const renderedComment = _jsDocs.renderComment.call(void 0, _nullishCoalesce(definition.description, () => ( definition.title)));

package/dist/swagger/typesExtractor.js

@@ -16,7 +16,8 @@ var _utils = require('../utils');
  */
  function getParameterType(
   param,
-  options
+  options,
+  context = 'schema'
 ) {
   const unknownType = options.preferAny ? 'any' : 'unknown';
 
@@ -24,7 +25,7 @@ var _utils = require('../utils');
     return unknownType;
   }
 
-  return getTypeFromSchemaResolved(param.schema, options);
+  return getTypeFromSchemaResolved(param.schema, options, `${context}.schema`);
 } exports.getParameterType = getParameterType;
 
 /**
@@ -35,9 +36,10 @@ var _utils = require('../utils');
  */
  function getTypeFromSchema(
   schema,
-  options
+  options,
+  context = 'schema'
 ) {
-  return getTypeFromSchemaResolved(schema, options);
+  return getTypeFromSchemaResolved(schema, options, context);
 } exports.getTypeFromSchema = getTypeFromSchema;
 
 /**
@@ -46,7 +48,8 @@ var _utils = require('../utils');
  */
 function getTypeFromSchemaResolved(
   schema,
-  options
+  options,
+  context
 ) {
   const unknownType = options.preferAny ? 'any' : 'unknown';
 
@@ -54,6 +57,17 @@ function getTypeFromSchemaResolved(
     return unknownType;
   }
 
+  if (typeof schema !== 'object' || Array.isArray(schema)) {
+    if (context.endsWith('.properties.$ref') && typeof schema === 'string') {
+      throw new Error(
+        `Invalid schema at ${context}: string value under properties.$ref is not a valid schema. ` +
+          'Did you mean to use schema.$ref at the root, or wrap it in a named property (for example properties.data.$ref)?'
+      );
+    }
+
+    throw new Error(`Invalid schema at ${context}: expected an object schema, got ${typeof schema}.`);
+  }
+
   if ('$ref' in schema) {
     const refName = schema.$ref.split('/').pop();
     return getSafeIdentifier(refName) || unknownType;
@@ -65,13 +79,13 @@ function getTypeFromSchemaResolved(
 
   // OpenAPI 3.1 nullable: type is an array containing 'null', e.g. ["string", "null"]
   if (Array.isArray(schema.type)) {
-    return getTypeFromOA31ArrayType(schema , options);
+    return getTypeFromOA31ArrayType(schema , options, context);
   }
 
   // OpenAPI 3.0 nullable: nullable: true
   const isNullable = 'nullable' in schema && schema.nullable === true;
   const isNullableSuffix = isNullable && options.nullableStrategy === 'include' ? ' | null' : '';
-  const type = getTypeFromSchemaInternal(schema, options);
+  const type = getTypeFromSchemaInternal(schema, options, context);
 
   if (isNullableSuffix && type.endsWith('| null')) {
     return type;
@@ -84,7 +98,11 @@ function getTypeFromSchemaResolved(
  * The presence of `"null"` in the array is the OA3.1 way of marking a field as nullable.
  * Respects `nullableStrategy` the same way as OA3.0 `nullable: true`.
  */
-function getTypeFromOA31ArrayType(schema, options) {
+function getTypeFromOA31ArrayType(
+  schema,
+  options,
+  context
+) {
   const unknownType = options.preferAny ? 'any' : 'unknown';
   const types = schema.type ;
   const isNullable = types.includes('null');
@@ -97,11 +115,17 @@ function getTypeFromOA31ArrayType(schema, options) {
   } else if (nonNullTypes.length === 1) {
     // Synthesize a single-type schema to reuse existing resolution logic
     const singleTypeSchema = { ...schema, type: nonNullTypes[0] } ;
-    baseType = getTypeFromSchemaInternal(singleTypeSchema, options);
+    baseType = getTypeFromSchemaInternal(singleTypeSchema, options, context);
   } else {
     // Multiple non-null types — resolve each independently and join as a union
     baseType = nonNullTypes
-      .map((t) => getTypeFromSchemaInternal({ ...schema, type: t } , options))
+      .map((t) =>
+        getTypeFromSchemaInternal(
+          { ...schema, type: t } ,
+          options,
+          `${context}.type`
+        )
+      )
       .join(' | ');
   }
 
@@ -129,22 +153,23 @@ function getTypeFromOA31ArrayType(schema, options) {
 
 function getTypeFromSchemaInternal(
   schema,
-  options
+  options,
+  context
 ) {
   const unknownType = options.preferAny ? 'any' : 'unknown';
 
   if ('allOf' in schema || 'oneOf' in schema || 'anyOf' in schema) {
-    return getTypeFromComposites(schema , options);
+    return getTypeFromComposites(schema , options, context);
   }
 
   if (schema.type === 'array') {
     if (schema.items) {
-      return `${getNestedTypeFromSchema(schema.items, options)}[]`;
+      return `${getNestedTypeFromSchema(schema.items, options, `${context}.items`)}[]`;
     }
     return `${unknownType}[]`;
   }
   if (schema.type === 'object') {
-    return getTypeFromObject(schema, options);
+    return getTypeFromObject(schema, options, undefined, context);
   }
   if ('enum' in schema) {
     return `${schema.enum.map((v) => JSON.stringify(v)).join(' | ')}`;
@@ -166,7 +191,8 @@ function getTypeFromSchemaInternal(
 
 function getNestedTypeFromSchema(
   schema,
-  options
+  options,
+  context
 ) {
   // OA3.0 nullable: true
   const isOA30NullableAndActive =
@@ -180,10 +206,10 @@ function getNestedTypeFromSchema(
     options.nullableStrategy === 'include';
 
   if (isOA30NullableAndActive || isOA31NullableAndActive || ('enum' in schema && schema.enum)) {
-    return `(${getTypeFromSchemaResolved(schema, options)})`;
+    return `(${getTypeFromSchemaResolved(schema, options, context)})`;
   }
 
-  return getTypeFromSchemaResolved(schema, options);
+  return getTypeFromSchemaResolved(schema, options, context);
 }
 
 /**
@@ -193,7 +219,8 @@ function getNestedTypeFromSchema(
 function getTypeFromObject(
   schema,
   options,
-  requiredOverride
+  requiredOverride,
+  context = 'schema'
 ) {
   const unknownType = options.preferAny ? 'any' : 'unknown';
   let objectWithNamedPropsType = '';
@@ -209,7 +236,11 @@ function getTypeFromObject(
       const isRequired = required.includes(prop);
       const safePropName = _utils.escapePropName.call(void 0, prop);
       result.push(
-        `${safePropName}${isRequired ? '' : '?'}: ${getTypeFromSchemaResolved(propDefinition, options)};`
+        `${safePropName}${isRequired ? '' : '?'}: ${getTypeFromSchemaResolved(
+          propDefinition,
+          options,
+          `${context}.properties.${prop}`
+        )};`
       );
     }
 
@@ -219,7 +250,9 @@ function getTypeFromObject(
   if (schema.additionalProperties) {
     const extraProps = schema.additionalProperties;
     objectWithIndexSignatureType = `{ [key: string]: ${
-      extraProps === true ? 'any' : getTypeFromSchemaResolved(extraProps, options)
+      extraProps === true
+        ? 'any'
+        : getTypeFromSchemaResolved(extraProps, options, `${context}.additionalProperties`)
     } }`;
   }
 
@@ -241,7 +274,11 @@ function getTypeFromObject(
 /**
  * Simplified way of extracting correct type from `anyOf`, `oneOf` or `allOf` schema.
  */
-function getTypeFromComposites(schema, options) {
+function getTypeFromComposites(
+  schema,
+  options,
+  context = 'schema'
+) {
   const composite = schema.allOf || schema.oneOf || schema.anyOf;
 
   if (!composite) {
@@ -253,7 +290,7 @@ function getTypeFromComposites(schema, options) {
 
   if (isUnionComposite && hasParentObjectShape) {
     const fallbackType = options.preferAny ? 'any' : 'unknown';
-    const parentObjectType = getTypeFromObject(schema, options);
+    const parentObjectType = getTypeFromObject(schema, options, undefined, context);
     const parentRequired = schema.required || [];
     const parentPropSet = new Set(Object.keys(schema.properties || {}));
 
@@ -271,10 +308,15 @@ function getTypeFromComposites(schema, options) {
             return isKnown;
           });
 
-          return getTypeFromObject(schema, options, Array.from(new Set([...parentRequired, ...validRequired])));
+          return getTypeFromObject(
+            schema,
+            options,
+            Array.from(new Set([...parentRequired, ...validRequired])),
+            context
+          );
         }
 
-        const subType = getTypeFromSchemaResolved(subSchema, options);
+        const subType = getTypeFromSchemaResolved(subSchema, options, `${context}.composite`);
         if (subType === fallbackType) {
           return parentObjectType;
         }
@@ -285,7 +327,7 @@ function getTypeFromComposites(schema, options) {
   }
 
   return composite
-    .map((s) => getTypeFromSchemaResolved(s, options))
+    .map((s, index) => getTypeFromSchemaResolved(s, options, `${context}.composite[${index}]`))
     .join(schema.allOf ? ' & ' : ' | ');
 }
 

package/dist/utils/utils.js

@@ -240,12 +240,11 @@ function resolveResponseRef(
 const sortByKey = (key) => (a, b) => (a[key] > b[key] ? 1 : b[key] > a[key] ? -1 : 0);
 
 const orderedContentTypes = [
-  'application/json',
-  'text/json',
   'text/plain',
   'application/x-www-form-urlencoded',
   'multipart/form-data',
 ];
+const preferredJsonContentTypes = ['application/json', 'text/json'];
  function getBestContentType(
   reqBody
 ) {
@@ -254,6 +253,19 @@ const orderedContentTypes = [
     return [null, null];
   }
 
+  const preferredJsonContentType = preferredJsonContentTypes.find((ct) => contentTypes.includes(ct));
+  if (preferredJsonContentType) {
+    const typeObject = reqBody.content[preferredJsonContentType];
+    const type = getContentType(preferredJsonContentType);
+    return [typeObject, type];
+  }
+
+  const jsonLikeContentType = contentTypes.find(isJsonLikeContentType);
+  if (jsonLikeContentType) {
+    const typeObject = reqBody.content[jsonLikeContentType];
+    return [typeObject, 'json'];
+  }
+
   const firstContentType = orderedContentTypes.find((ct) => contentTypes.includes(ct));
   if (firstContentType) {
     const typeObject = reqBody.content[firstContentType];
@@ -266,6 +278,11 @@ const orderedContentTypes = [
   return [typeObject, type];
 } exports.getBestContentType = getBestContentType;
 
+function isJsonLikeContentType(contentType) {
+  const normalized = contentType.split(';')[0].trim().toLowerCase();
+  return normalized === 'application/*+json' || /^application\/.+\+json$/.test(normalized);
+}
+
 function getContentType(type) {
   if (type === 'application/x-www-form-urlencoded') {
     return 'urlencoded';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swaggie",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "Generate a fully typed TypeScript API client from your OpenAPI 3 spec",
   "author": {
     "name": "Piotr Dabrowski",

package/templates/fetch/operation.ejs

@@ -11,6 +11,21 @@ $config?: RequestInit
 '<%= parameter.originalName %>': <%= parameter.name %>,
       <% }); %>})}<% } %>`;
 
+<% if(it.headers && it.headers.length > 0) { %>
+    const { headers: $configHeaders, ...$configRest } = $config ?? {};
+    const headers = new Headers({
+<% it.headers.forEach((parameter) => { %>
+<% if (parameter.value) { %>
+      '<%= parameter.originalName %>': '<%= parameter.value %>',
+<% } else { %>
+      '<%= parameter.originalName %>': <%= parameter.name %> ?? '',
+<% } %>
+<% }); %>
+    });
+    if ($configHeaders) {
+      new Headers($configHeaders).forEach((value, key) => headers.set(key, value));
+    }
+
     return fetch(url, {
       method: '<%= it.method %>',
 <% if(it.body) { %>
@@ -22,19 +37,24 @@ $config?: RequestInit
       body: <%= it.body.name %>,
 <% } %>
 <% } %>
-<% if(it.headers && it.headers.length > 0) { %>
-      headers: {
-  <% it.headers.forEach((parameter) => { %>
-    <% if (parameter.value) { %>
-  '<%= parameter.originalName %>': '<%= parameter.value %>',
-    <% } else { %>
-  '<%= parameter.originalName %>': <%= parameter.name %> ?? '',
-    <% } %>
-  <% }); %>
-},
+      headers,
+      ...$configRest,
+    })
+<% } else { %>
+    return fetch(url, {
+      method: '<%= it.method %>',
+<% if(it.body) { %>
+<% if(it.body.contentType === 'json') { %>
+      body: JSON.stringify(<%= it.body.name %>),
+<% } else if(it.body.contentType === 'urlencoded') { %>
+      body: new URLSearchParams(<%= it.body.name %> as any),
+<% } else { %>
+      body: <%= it.body.name %>,
+<% } %>
 <% } %>
       ...$config,
     })
+<% } %>
 <% if(it.responseContentType === 'binary') { %>
     .then((response) => response.blob() as Promise<<%~ it.returnType %>>);
 <% } else if(it.responseContentType === 'text') { %>