swaggie 1.7.1 → 1.8.1

package/README.md

@@ -78,7 +78,10 @@ swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore
 -o, --out <filePath>      Output file path (omit to print to stdout)
 -b, --baseUrl <string>    Default base URL for the generated client (default: "")
 -t, --template <string>   Template to use for code generation (default: "axios")
-    --preferAny           Use "any" instead of "unknown" for untyped values (default: false)
+ -m, --mode <mode>         Generation mode: "full" or "schemas" (default: "full")
+ -d, --schemaStyle <style> Schema object style: "interface" or "type" (default: "interface")
+    --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
@@ -119,6 +122,9 @@ swaggie -c swaggie.config.json
   "servicePrefix": "",
   "dateFormat": "Date",
   "nullableStrategy": "ignore",
+  "generationMode": "full",
+  "schemaDeclarationStyle": "interface",
+  "enumDeclarationStyle": "union",
   "queryParamsSerialization": {
     "arrayFormat": "repeat",
     "allowDots": true
@@ -255,6 +261,34 @@ OpenAPI 3.0 allows fields to be marked as `nullable: true`. Swaggie gives you th
 // nullableStrategy: "nullableAsOptional"  →  tenant?: string;
 ```
 
+### Generation Mode
+
+Use `generationMode` (or CLI `--mode`) to control what gets generated:
+
+| Value       | Behavior                                                                       |
+| ----------- | ------------------------------------------------------------------------------ |
+| `"full"`   | Generates full client code + used schemas (default, existing behavior)         |
+| `"schemas"`| Generates only schemas and includes all component schemas by default            |
+
+`"schemas"` mode intentionally does not run the used-schema heuristic.
+
+### Schema Declaration Style
+
+Use `schemaDeclarationStyle` (or CLI `--schemaStyle`) to control object schema output:
+
+| Value         | Behavior                                                                 |
+| ------------- | ------------------------------------------------------------------------ |
+| `"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.
@@ -336,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

@@ -15,6 +15,19 @@ const arrayFormatOption = new (0, _commander.Option)(
 
 const packageJson = readPackageJson();
 
+const modeOption = new (0, _commander.Option)('-m, --mode <mode>', 'Generation mode').choices([
+  'full',
+  'schemas',
+]);
+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
   .version(packageJson.version)
@@ -53,7 +66,10 @@ program
     '--allowDots <bool>',
     'Determines if dots should be used for serialization object properties'
   )
-  .addOption(arrayFormatOption);
+  .addOption(arrayFormatOption)
+  .addOption(modeOption)
+  .addOption(schemaStyleOption)
+  .addOption(enumStyleOption);
 
 program.parse(process.argv);
 

package/dist/gen/genTypes.js

@@ -46,6 +46,7 @@ function renderSchema(
   schema,
   options
 ) {
+  const useTypeAliases = options.schemaDeclarationStyle === 'type';
   const safeName = _swagger.getSafeIdentifier.call(void 0, name);
   if (!safeName) {
     console.warn(`Skipping schema ${name} because it is not a valid identifier`);
@@ -69,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');
   }
 
@@ -81,13 +82,28 @@ 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(' & ');
+      result.push(`export type ${safeName} = ${compositeTypes};`);
+      return `${result.join('\n')}\n`;
+    }
+
     const extensions = types ? `extends ${types.join(', ')} ` : '';
     result.push(`export interface ${safeName} ${extensions}{`);
-
-    const mergedSchema = getMergedCompositeObjects(schema);
-    result.push(generateObjectTypeContents(mergedSchema, options));
+    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`;
@@ -97,26 +113,26 @@ function renderSchema(
     result.push(`export type ${safeName} = ${generateItemsType(schema.items, options)}[];`);
     return result.join('\n');
   } else {
-    result.push(`export interface ${safeName} {`);
-    result.push(generateObjectTypeContents(schema, options));
-  }
+    const objectType = _swagger.getTypeFromSchema.call(void 0, schema, options);
+    const hasAdditionalProperties = !!schema.additionalProperties;
 
-  return `${result.join('\n')}}\n`;
-}
+    const objectContents = generateObjectTypeContents(schema, options);
+    if (hasAdditionalProperties) {
+      result.push(`export type ${safeName} = ${objectType};`);
+      return `${result.join('\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 '';
+    if (useTypeAliases) {
+      result.push(`export type ${safeName} = {`);
+      result.push(objectContents);
+      return `${result.join('\n')}\n};\n`;
+    }
+
+    result.push(`export interface ${safeName} {`);
+    result.push(objectContents);
   }
 
-  return composite.map((s) => _swagger.getTypeFromSchema.call(void 0, s, options)).join(' | ');
+  return `${result.join('\n')}\n}\n`;
 }
 
 /**
@@ -167,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.
  */
@@ -198,7 +239,10 @@ function renderTypeProp(
   const type = _swagger.getTypeFromSchema.call(void 0, definition, options);
 
   if ('description' in definition || 'title' in definition) {
-    lines.push(_jsDocs.renderComment.call(void 0, _nullishCoalesce(definition.description, () => ( definition.title))));
+    const renderedComment = _jsDocs.renderComment.call(void 0, _nullishCoalesce(definition.description, () => ( definition.title)));
+    if (renderedComment) {
+      lines.push(indentComment(renderedComment, '  '));
+    }
   }
 
   const isOptional = !required || isNullableAsOptional(definition, options);
@@ -211,6 +255,13 @@ function renderTypeProp(
   return lines.join('\n');
 }
 
+function indentComment(comment, indent) {
+  return comment
+    .split('\n')
+    .map((line) => `${indent}${line}`)
+    .join('\n');
+}
+
 /**
  * When nullableAsOptional strategy is set, nullable properties are treated as optional.
  * Supports both OA3.0 (nullable: true) and OA3.1 (type: ["string", "null"]).
@@ -242,7 +293,7 @@ function getMergedCompositeObjects(schema) {
     subSchemas.push(safeSchema);
   }
 
-  return deepMerge({}, ...subSchemas);
+  return deepMerge({}, ...subSchemas) ;
 }
 
 function isObject(item) {

package/dist/gen/index.js

@@ -9,8 +9,14 @@ var _utils = require('../utils');
   spec,
   options
 ) {
-  let fileContents = await _genOperations2.default.call(void 0, spec, options);
-  fileContents += _genTypes2.default.call(void 0, spec, options);
+  let fileContents = '';
+
+  if (options.generationMode === 'schemas') {
+    fileContents = _genTypes2.default.call(void 0, spec, options, false);
+  } else {
+    fileContents = await _genOperations2.default.call(void 0, spec, options);
+    fileContents += _genTypes2.default.call(void 0, spec, options);
+  }
 
   if (options.out) {
     const destFile = _utils.prepareOutputFilename.call(void 0, options.out);

package/dist/index.js

@@ -34,7 +34,9 @@ function verifyOptions(options) {
 }
 
 function gen(spec, options) {
-  _utils.loadAllTemplateFiles.call(void 0, options.template);
+  if (options.generationMode === 'full') {
+    _utils.loadAllTemplateFiles.call(void 0, options.template);
+  }
 
   return _gen2.default.call(void 0, spec, options);
 }
@@ -76,7 +78,16 @@ function readFile(filePath) {
  * object where every defaultable field is guaranteed to be present.
  */
  function prepareAppOptions(cliOpts) {
-  const { allowDots, arrayFormat, template, queryParamsSerialization = {}, ...rest } = cliOpts;
+  const {
+    allowDots,
+    arrayFormat,
+    mode,
+    schemaStyle,
+    enumStyle,
+    template,
+    queryParamsSerialization = {},
+    ...rest
+  } = cliOpts;
   const mergedQueryParamsSerialization = {
     ..._swagger.APP_DEFAULTS.queryParamsSerialization,
     ...Object.fromEntries(
@@ -91,6 +102,11 @@ function readFile(filePath) {
     template: _nullishCoalesce(template, () => ( _swagger.APP_DEFAULTS.template)),
     servicePrefix: _nullishCoalesce(rest.servicePrefix, () => ( _swagger.APP_DEFAULTS.servicePrefix)),
     nullableStrategy: _nullishCoalesce(rest.nullableStrategy, () => ( _swagger.APP_DEFAULTS.nullableStrategy)),
+    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.
@@ -262,6 +330,9 @@ function getTypeFromComposites(schema, options) {
   template: 'axios',
   servicePrefix: '',
   nullableStrategy: 'ignore',
+  generationMode: 'full',
+  schemaDeclarationStyle: 'interface',
+  enumDeclarationStyle: 'union',
   queryParamsSerialization: {
     allowDots: true,
     arrayFormat: 'repeat',
@@ -279,6 +350,9 @@ function getTypeFromComposites(schema, options) {
     template: _nullishCoalesce(opts.template, () => ( exports.APP_DEFAULTS.template)),
     servicePrefix: _nullishCoalesce(opts.servicePrefix, () => ( exports.APP_DEFAULTS.servicePrefix)),
     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

@@ -29,6 +29,12 @@ export interface ClientOptions {
     nullableStrategy?: NullableStrategy;
     /** Options for query parameters serialization */
     queryParamsSerialization: QueryParamsSerializationOptions;
+    /** Controls whether to generate full client code or only component schemas */
+    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 */
@@ -40,6 +46,9 @@ export interface ClientOptions {
 export interface CliOptions extends FullAppOptions {
     allowDots?: boolean;
     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 */
@@ -50,6 +59,9 @@ export type HttpMethod = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head'
 export type DateSupport = 'string' | 'Date';
 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
@@ -59,6 +71,9 @@ export interface AppOptions extends ClientOptions {
     template: Template;
     servicePrefix: string;
     nullableStrategy: NullableStrategy;
+    generationMode: GenerationMode;
+    schemaDeclarationStyle: SchemaDeclarationStyle;
+    enumDeclarationStyle: EnumDeclarationStyle;
     queryParamsSerialization: {
         allowDots: boolean;
         arrayFormat: ArrayFormat;

package/package.json

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