swaggie 1.8.0 → 1.8.1

package/README.md

@@ -80,7 +80,8 @@ swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore
 -t, --template <string>   Template to use for code generation (default: "axios")
  -m, --mode <mode>         Generation mode: "full" or "schemas" (default: "full")
  -d, --schemaStyle <style> Schema object style: "interface" or "type" (default: "interface")
-    --preferAny           Use "any" instead of "unknown" for untyped values (default: false)
+    --enumStyle <style>    Enum style for plain string enums: "union" or "enum" (default: "union")
+     --preferAny           Use "any" instead of "unknown" for untyped values (default: false)
     --skipDeprecated      Exclude deprecated operations from the output (default: false)
     --servicePrefix       Prefix for service names — useful when generating multiple APIs
     --allowDots           Use dot notation to serialize nested object query params
@@ -123,6 +124,7 @@ swaggie -c swaggie.config.json
   "nullableStrategy": "ignore",
   "generationMode": "full",
   "schemaDeclarationStyle": "interface",
+  "enumDeclarationStyle": "union",
   "queryParamsSerialization": {
     "arrayFormat": "repeat",
     "allowDots": true
@@ -279,6 +281,14 @@ Use `schemaDeclarationStyle` (or CLI `--schemaStyle`) to control object schema o
 | `"interface"`| `export interface Tag { ... }` (default)                                |
 | `"type"`     | `export type Tag = { ... };`                                             |
 
+### Enum Declaration Style
+
+Use `enumDeclarationStyle` (or CLI `--enumStyle`) for plain string enums:
+- `"union"` (default): `export type Status = "active" | "disabled";`
+- `"enum"`: `export enum Status { active = "active", disabled = "disabled" }`
+
+Note: this applies only to plain string enums. Non-string enums are still emitted as union types.
+
 ### Parameter Modifiers
 
 Sometimes an API spec marks a parameter as required, but your client handles it in an interceptor and you don't want it cluttering every method signature. Parameter modifiers let you override this globally without touching the spec.
@@ -360,12 +370,12 @@ Swaggie only needs a JSON or YAML OpenAPI spec file — it does not require a ru
 | Supported                                                                      | Not Supported                                        |
 | ------------------------------------------------------------------------------ | ---------------------------------------------------- |
 | OpenAPI 3.0, 3.1, 3.2                                                          | Swagger / OpenAPI 2.0                                |
-| `allOf`, `oneOf`, `anyOf`, `$ref`                                              | `not` keyword                                        |
+| `allOf`, `oneOf`, `anyOf`, `$ref`, external $refs                              | `not` keyword                                        |
 | Spec formats: JSON, YAML                                                       | Very complex query parameter structures              |
 | Extensions: `x-position`, `x-name`, `x-enumNames`, `x-enum-varnames`           | Multiple response types (only the first is used)     |
 | Content types: JSON, plain text, multipart/form-data                           | Multiple request body types (only the first is used) |
-| Content types: `application/x-www-form-urlencoded`, `application/octet-stream` | References to external spec files                    |
-| Various enum definition styles                                                 | OpenAPI callbacks and webhooks                       |
+| Content types: `application/x-www-form-urlencoded`, `application/octet-stream` | OpenAPI callbacks and webhooks                       |
+| Various enum definition styles, support for additionalProperties               |                                                      |
 | Nullable types, path inheritance, JSDoc descriptions                           |                                                      |
 | Remote URLs and local file paths as spec source                                |                                                      |
 | Grouping by tags, graceful handling of duplicate operation IDs                 |                                                      |

package/dist/cli.js

@@ -23,6 +23,10 @@ const schemaStyleOption = new (0, _commander.Option)(
   '-d, --schemaStyle <style>',
   'Schema object declaration style'
 ).choices(['interface', 'type']);
+const enumStyleOption = new (0, _commander.Option)(
+  '--enumStyle <style>',
+  'Enum declaration style for plain string enums'
+).choices(['union', 'enum']);
 
 const program = new (0, _commander.Command)();
 program
@@ -64,7 +68,8 @@ program
   )
   .addOption(arrayFormatOption)
   .addOption(modeOption)
-  .addOption(schemaStyleOption);
+  .addOption(schemaStyleOption)
+  .addOption(enumStyleOption);
 
 program.parse(process.argv);
 

package/dist/gen/genTypes.js

@@ -70,7 +70,7 @@ function renderSchema(
     return result.join('\n');
   }
   if ('enum' in schema) {
-    result.push(renderEnumType(safeName, schema));
+    result.push(renderEnumType(safeName, schema, options));
     return result.join('\n');
   }
 
@@ -83,7 +83,15 @@ 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 hasAdditionalProperties = !!mergedSchema.additionalProperties;
+
+    if (hasAdditionalProperties) {
+      const compositeTypes = [...types, objectType].join(' & ');
+      result.push(`export type ${safeName} = ${compositeTypes};`);
+      return `${result.join('\n')}\n`;
+    }
 
     if (useTypeAliases) {
       const compositeTypes = [...types, `{${objectContents ? `\n${objectContents}\n` : ''}}`].join(' & ');
@@ -95,7 +103,7 @@ function renderSchema(
     result.push(`export interface ${safeName} ${extensions}{`);
     result.push(objectContents);
   } else if ('oneOf' in schema || 'anyOf' in schema) {
-    const typeDefinition = getTypesFromAnyOrOneOf(schema, options);
+    const typeDefinition = _swagger.getTypeFromSchema.call(void 0, schema, options);
     result.push(`export type ${safeName} = ${typeDefinition};`);
 
     return `${result.join('\n')}\n`;
@@ -105,7 +113,15 @@ 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 hasAdditionalProperties = !!schema.additionalProperties;
+
     const objectContents = generateObjectTypeContents(schema, options);
+    if (hasAdditionalProperties) {
+      result.push(`export type ${safeName} = ${objectType};`);
+      return `${result.join('\n')}\n`;
+    }
+
     if (useTypeAliases) {
       result.push(`export type ${safeName} = {`);
       result.push(objectContents);
@@ -119,21 +135,6 @@ function renderSchema(
   return `${result.join('\n')}\n}\n`;
 }
 
-/**
- * Generates the type definition for an `anyOf` or `oneOf` schema.
- * @param schema - The schema object to generate the type definition for.
- * @param options - The options for the generation.
- * @returns The type definition for the `anyOf` or `oneOf` schema.
- */
-function getTypesFromAnyOrOneOf(schema, options) {
-  const composite = schema.allOf || schema.oneOf || schema.anyOf;
-  if (!composite) {
-    return '';
-  }
-
-  return composite.map((s) => _swagger.getTypeFromSchema.call(void 0, s, options)).join(' | ');
-}
-
 /**
  * Generates the inline contents of an object type.
  */
@@ -182,11 +183,36 @@ function renderExtendedEnumType(name, def) {
 /**
  * Render simple enum types (just a union of values)
  */
-function renderEnumType(name, def) {
+function renderEnumType(name, def, options) {
+  if (options.enumDeclarationStyle === 'enum' && shouldRenderStringEnumDeclaration(def)) {
+    return renderStringEnumDeclaration(name, def);
+  }
+
   const values = def.enum.map((v) => (typeof v === 'number' ? v : `"${v}"`)).join(' | ');
   return `export type ${name} = ${values};\n`;
 }
 
+function shouldRenderStringEnumDeclaration(def)
+
+ {
+  return (
+    def.type === 'string' &&
+    Array.isArray(def.enum) &&
+    def.enum.every((value) => typeof value === 'string')
+  );
+}
+
+function renderStringEnumDeclaration(name, def) {
+  let res = `export enum ${name} {\n`;
+  for (let index = 0; index < def.enum.length; index++) {
+    const value = def.enum[index];
+    const memberName = _nullishCoalesce(_utils.escapePropName.call(void 0, value), () => ( `VALUE_${index}`));
+    res += `  ${memberName} = ${JSON.stringify(value)},\n`;
+  }
+
+  return `${res}}\n`;
+}
+
 /**
  * OpenApi 3.1 introduced a new way to define enums that we support here.
  */
@@ -267,7 +293,7 @@ function getMergedCompositeObjects(schema) {
     subSchemas.push(safeSchema);
   }
 
-  return deepMerge({}, ...subSchemas);
+  return deepMerge({}, ...subSchemas) ;
 }
 
 function isObject(item) {

package/dist/index.js

@@ -83,6 +83,7 @@ function readFile(filePath) {
     arrayFormat,
     mode,
     schemaStyle,
+    enumStyle,
     template,
     queryParamsSerialization = {},
     ...rest
@@ -104,6 +105,8 @@ function readFile(filePath) {
     generationMode: _nullishCoalesce(_nullishCoalesce(mode, () => ( rest.generationMode)), () => ( _swagger.APP_DEFAULTS.generationMode)),
     schemaDeclarationStyle:
       _nullishCoalesce(_nullishCoalesce(schemaStyle, () => ( rest.schemaDeclarationStyle)), () => ( _swagger.APP_DEFAULTS.schemaDeclarationStyle)),
+    enumDeclarationStyle:
+      _nullishCoalesce(_nullishCoalesce(enumStyle, () => ( rest.enumDeclarationStyle)), () => ( _swagger.APP_DEFAULTS.enumDeclarationStyle)),
     queryParamsSerialization: mergedQueryParamsSerialization,
   };
 } exports.prepareAppOptions = prepareAppOptions;

package/dist/swagger/typesExtractor.js

@@ -192,20 +192,16 @@ function getNestedTypeFromSchema(
  */
 function getTypeFromObject(
   schema,
-  options
+  options,
+  requiredOverride
 ) {
   const unknownType = options.preferAny ? 'any' : 'unknown';
-
-  if (schema.additionalProperties) {
-    const extraProps = schema.additionalProperties;
-    return `{ [key: string]: ${
-      extraProps === true ? 'any' : getTypeFromSchemaResolved(extraProps, options)
-    } }`;
-  }
+  let objectWithNamedPropsType = '';
+  let objectWithIndexSignatureType = '';
 
   if (schema.properties) {
     const props = Object.keys(schema.properties);
-    const required = schema.required || [];
+    const required = _nullishCoalesce(_nullishCoalesce(requiredOverride, () => ( schema.required)), () => ( []));
     const result = [];
 
     for (const prop of props) {
@@ -217,7 +213,26 @@ function getTypeFromObject(
       );
     }
 
-    return `{ ${result.join('\n')} }`;
+    objectWithNamedPropsType = `{ ${result.join('\n')} }`;
+  }
+
+  if (schema.additionalProperties) {
+    const extraProps = schema.additionalProperties;
+    objectWithIndexSignatureType = `{ [key: string]: ${
+      extraProps === true ? 'any' : getTypeFromSchemaResolved(extraProps, options)
+    } }`;
+  }
+
+  if (objectWithNamedPropsType && objectWithIndexSignatureType) {
+    return `${objectWithNamedPropsType} & ${objectWithIndexSignatureType}`;
+  }
+
+  if (objectWithNamedPropsType) {
+    return objectWithNamedPropsType;
+  }
+
+  if (objectWithIndexSignatureType) {
+    return objectWithIndexSignatureType;
   }
 
   return unknownType;
@@ -229,11 +244,64 @@ function getTypeFromObject(
 function getTypeFromComposites(schema, options) {
   const composite = schema.allOf || schema.oneOf || schema.anyOf;
 
+  if (!composite) {
+    return options.preferAny ? 'any' : 'unknown';
+  }
+
+  const isUnionComposite = !!schema.oneOf || !!schema.anyOf;
+  const hasParentObjectShape = !!schema.properties || !!schema.additionalProperties;
+
+  if (isUnionComposite && hasParentObjectShape) {
+    const fallbackType = options.preferAny ? 'any' : 'unknown';
+    const parentObjectType = getTypeFromObject(schema, options);
+    const parentRequired = schema.required || [];
+    const parentPropSet = new Set(Object.keys(schema.properties || {}));
+
+    return composite
+      .map((subSchema) => {
+        if (!('$ref' in subSchema) && isRequiredOnlyCompositeBranch(subSchema)) {
+          const branchRequired = subSchema.required || [];
+          const validRequired = branchRequired.filter((name) => {
+            const isKnown = parentPropSet.has(name);
+            if (!isKnown) {
+              console.warn(
+                `Composite required key '${name}' is not present in schema properties and will be ignored.`
+              );
+            }
+            return isKnown;
+          });
+
+          return getTypeFromObject(schema, options, Array.from(new Set([...parentRequired, ...validRequired])));
+        }
+
+        const subType = getTypeFromSchemaResolved(subSchema, options);
+        if (subType === fallbackType) {
+          return parentObjectType;
+        }
+
+        return `${parentObjectType} & ${subType}`;
+      })
+      .join(' | ');
+  }
+
   return composite
     .map((s) => getTypeFromSchemaResolved(s, options))
     .join(schema.allOf ? ' & ' : ' | ');
 }
 
+function isRequiredOnlyCompositeBranch(schema) {
+  return (
+    Array.isArray(schema.required) &&
+    !schema.type &&
+    !schema.properties &&
+    !schema.additionalProperties &&
+    !schema.allOf &&
+    !schema.oneOf &&
+    !schema.anyOf &&
+    !schema.enum
+  );
+}
+
 /**
  * Escapes name so it can be used as a valid identifier in the generated code.
  * Component names can contain certain characters that are not allowed in identifiers.
@@ -264,6 +332,7 @@ function getTypeFromComposites(schema, options) {
   nullableStrategy: 'ignore',
   generationMode: 'full',
   schemaDeclarationStyle: 'interface',
+  enumDeclarationStyle: 'union',
   queryParamsSerialization: {
     allowDots: true,
     arrayFormat: 'repeat',
@@ -283,6 +352,7 @@ function getTypeFromComposites(schema, options) {
     nullableStrategy: _nullishCoalesce(opts.nullableStrategy, () => ( exports.APP_DEFAULTS.nullableStrategy)),
     generationMode: _nullishCoalesce(opts.generationMode, () => ( exports.APP_DEFAULTS.generationMode)),
     schemaDeclarationStyle: _nullishCoalesce(opts.schemaDeclarationStyle, () => ( exports.APP_DEFAULTS.schemaDeclarationStyle)),
+    enumDeclarationStyle: _nullishCoalesce(opts.enumDeclarationStyle, () => ( exports.APP_DEFAULTS.enumDeclarationStyle)),
     queryParamsSerialization: {
       ...exports.APP_DEFAULTS.queryParamsSerialization,
       ...opts.queryParamsSerialization,

package/dist/types.d.ts

@@ -33,6 +33,8 @@ export interface ClientOptions {
     generationMode?: GenerationMode;
     /** Controls whether object schemas are emitted as interfaces or type aliases */
     schemaDeclarationStyle?: SchemaDeclarationStyle;
+    /** Controls whether plain string enums are emitted as unions or TypeScript enums */
+    enumDeclarationStyle?: EnumDeclarationStyle;
     /** Offers ability to adjust the OpenAPI spec before it is processed */
     modifiers?: {
         /** Global-level modifiers for parameter with a given name */
@@ -46,6 +48,7 @@ export interface CliOptions extends FullAppOptions {
     arrayFormat?: ArrayFormat;
     mode?: GenerationMode;
     schemaStyle?: SchemaDeclarationStyle;
+    enumStyle?: EnumDeclarationStyle;
 }
 export interface FullAppOptions extends ClientOptions {
     /** Path to the configuration file that contains actual config to be used */
@@ -58,6 +61,7 @@ export type ArrayFormat = 'indices' | 'repeat' | 'brackets';
 export type NullableStrategy = 'include' | 'nullableAsOptional' | 'ignore';
 export type GenerationMode = 'full' | 'schemas';
 export type SchemaDeclarationStyle = 'interface' | 'type';
+export type EnumDeclarationStyle = 'union' | 'enum';
 /**
  * Internal options type used throughout the app after `prepareAppOptions` has run.
  * All fields that have defaults are required here so the rest of the codebase never
@@ -69,6 +73,7 @@ export interface AppOptions extends ClientOptions {
     nullableStrategy: NullableStrategy;
     generationMode: GenerationMode;
     schemaDeclarationStyle: SchemaDeclarationStyle;
+    enumDeclarationStyle: EnumDeclarationStyle;
     queryParamsSerialization: {
         allowDots: boolean;
         arrayFormat: ArrayFormat;

package/package.json

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