swaggie 1.8.4 → 1.8.6

package/README.md

@@ -1,5 +1,5 @@
 <div style="text-align: center; margin: 0px auto 30px; max-width: 600px">
-  <img src="./swaggie.svg" alt="Swaggie logo">
+  <img src="./docs/public/swaggie-full.png" alt="Swaggie logo">
 </div>
 
 # Swaggie
@@ -387,7 +387,7 @@ Swaggie only needs a JSON or YAML OpenAPI spec file — it does not require a ru
 ## Used By
 
 <div style="display: flex; gap: 1rem;">
-<a href="https://www.britishcouncil.org"><img alt="British Council" src="https://upload.wikimedia.org/wikipedia/commons/thumb/e/e1/BritishCouncil.png/320px-BritishCouncil.png" style="height: 50px;" /></a>
-<a href="https://kpmg.com/"><img alt="KPMG" src="https://upload.wikimedia.org/wikipedia/commons/thumb/3/31/KPMG.svg/320px-KPMG.svg.png" style="height: 50px;" /></a>
-<a href="https://klarna.com/"><img alt="Klarna" src="https://upload.wikimedia.org/wikipedia/commons/4/40/Klarna_Payment_Badge.svg" style="height: 50px;" /></a>
+<a href="https://www.britishcouncil.org"><img alt="British Council" src="./docs/public/used-in/bc-logo.png" /></a>
+<a href="https://kpmg.com/"><img alt="KPMG" src="./docs/public/used-in/kpmg-logo.png" /></a>
+<a href="https://klarna.com/"><img alt="Klarna" src="./docs/public/used-in/klarna-logo.png" /></a>
 </div>

package/dist/browser.js

@@ -72,6 +72,7 @@ async function generateCode(spec, options) {
     mode,
     schemaStyle,
     enumStyle,
+    enumNamesStyle,
     nullables,
     template,
     queryParamsSerialization = {},
@@ -96,6 +97,15 @@ async function generateCode(spec, options) {
       _nullishCoalesce(_nullishCoalesce(schemaStyle, () => ( rest.schemaDeclarationStyle)), () => ( _swagger.APP_DEFAULTS.schemaDeclarationStyle)),
     enumDeclarationStyle:
       _nullishCoalesce(_nullishCoalesce(enumStyle, () => ( rest.enumDeclarationStyle)), () => ( _swagger.APP_DEFAULTS.enumDeclarationStyle)),
+    enumNamesStyle: normalizeEnumNamesStyle(enumNamesStyle),
     queryParamsSerialization: mergedQueryParamsSerialization,
   };
 } exports.prepareAppOptions = prepareAppOptions;
+
+function normalizeEnumNamesStyle(value) {
+  if (!value) return _swagger.APP_DEFAULTS.enumNamesStyle;
+  const lower = value.toLowerCase();
+  if (lower === 'pascal' || lower === 'pascalcase') return 'PascalCase';
+  if (lower === 'original') return 'original';
+  return _swagger.APP_DEFAULTS.enumNamesStyle;
+}

package/dist/cli.js

@@ -27,6 +27,10 @@ const enumStyleOption = new (0, _commander.Option)(
   '--enumStyle <style>',
   'Enum declaration style for plain string enums'
 ).choices(['union', 'enum']);
+const enumNamesStyleOption = new (0, _commander.Option)(
+  '--enumNamesStyle <style>',
+  'Controls how enum member names are formatted (only with --enumStyle enum)'
+).choices(['original', 'PascalCase', 'pascal']);
 const dateFormatOption = new (0, _commander.Option)(
   '--dateFormat <format>',
   'How date fields are emitted in generated types'
@@ -78,6 +82,7 @@ program
   .addOption(modeOption)
   .addOption(schemaStyleOption)
   .addOption(enumStyleOption)
+  .addOption(enumNamesStyleOption)
   .addOption(dateFormatOption)
   .addOption(nullableStrategyOption);
 

package/dist/gen/genTypes.js

@@ -88,19 +88,30 @@ function renderSchema(
     const objectContents = generateObjectTypeContents(mergedSchema, options, schemaContext);
     const hasAdditionalProperties = !!mergedSchema.additionalProperties;
 
+    // Detect "orphan" required fields: top-level `required` entries that reference
+    // properties from $ref types rather than inline properties. For these we generate
+    // Required<Pick<...>> to enforce non-optionality in TypeScript.
+    const requiredPickType = getRequiredPickType(schema, mergedSchema, types);
+
     if (hasAdditionalProperties) {
-      const compositeTypes = [...types, objectType].join(' & ');
+      const compositeTypes = [...types, requiredPickType, objectType].filter(Boolean).join(' & ');
       result.push(`export type ${safeName} = ${compositeTypes};`);
       return `${result.join('\n')}\n`;
     }
 
-    if (useTypeAliases) {
-      const compositeTypes = [...types, `{${objectContents ? `\n${objectContents}\n` : ''}}`].join(' & ');
+    if (useTypeAliases || requiredPickType) {
+      // When requiredPickType is present we must use type alias (intersection) style,
+      // because `interface extends` does not allow extending two types that declare the
+      // same property with different optionality (e.g. `Team` with `id?` and
+      // `Required<Pick<Team, 'id'>>` with `id` — TS2320).
+      const objectLiteral = objectContents ? `{\n${objectContents}\n}` : '';
+      const allTypes = [...types, requiredPickType, objectLiteral].filter(Boolean);
+      const compositeTypes = allTypes.join(' & ');
       result.push(`export type ${safeName} = ${compositeTypes};`);
       return `${result.join('\n')}\n`;
     }
 
-    const extensions = types ? `extends ${types.join(', ')} ` : '';
+    const extensions = types.length ? `extends ${types.join(', ')} ` : '';
     result.push(`export interface ${safeName} ${extensions}{`);
     result.push(objectContents);
   } else if ('oneOf' in schema || 'anyOf' in schema) {
@@ -190,7 +201,7 @@ function renderExtendedEnumType(name, def) {
  */
 function renderEnumType(name, def, options) {
   if (options.enumDeclarationStyle === 'enum' && shouldRenderStringEnumDeclaration(def)) {
-    return renderStringEnumDeclaration(name, def);
+    return renderStringEnumDeclaration(name, def, options);
   }
 
   const values = def.enum.map((v) => (typeof v === 'number' ? v : `"${v}"`)).join(' | ');
@@ -207,17 +218,38 @@ function shouldRenderStringEnumDeclaration(def)
   );
 }
 
-function renderStringEnumDeclaration(name, def) {
+function renderStringEnumDeclaration(
+  name,
+  def,
+  options
+) {
+  const usePascalCase = options.enumNamesStyle === 'PascalCase';
   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}`));
+    const rawName = usePascalCase ? toPascalCase(value) : value;
+    const memberName = _nullishCoalesce(_utils.escapePropName.call(void 0, rawName), () => ( `VALUE_${index}`));
     res += `  ${memberName} = ${JSON.stringify(value)},\n`;
   }
 
   return `${res}}\n`;
 }
 
+/**
+ * Converts a string to PascalCase.
+ * Splits on non-alphanumeric characters (spaces, hyphens, dots, underscores, etc.)
+ * and capitalizes the first letter of each segment.
+ *
+ * Examples: "org name" → "OrgName", "my-value" → "MyValue", "some.thing" → "SomeThing"
+ */
+function toPascalCase(value) {
+  return value
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join('');
+}
+
 /**
  * OpenApi 3.1 introduced a new way to define enums that we support here.
  */
@@ -288,14 +320,40 @@ function isNullableAsOptional(
   );
 }
 
+/**
+ * Detects "orphan" required fields: top-level `required` entries that are not covered
+ * by inline `properties` in the merged schema. For these fields, we generate a
+ * `Required<Pick<RefType, 'prop1' | 'prop2'>>` expression to enforce non-optionality.
+ *
+ * @returns A `Required<Pick<...>>` type string, or an empty string if not applicable.
+ */
+function getRequiredPickType(
+  originalSchema,
+  mergedSchema,
+  refTypes
+) {
+  const topLevelRequired = originalSchema.required || [];
+  if (!topLevelRequired.length || !refTypes.length) return '';
+
+  const inlineProps = Object.keys(mergedSchema.properties || {});
+  const orphanRequired = topLevelRequired.filter((r) => !inlineProps.includes(r));
+  if (!orphanRequired.length) return '';
+
+  const propsUnion = orphanRequired.map((p) => `'${p}'`).join(' | ');
+  const baseType = refTypes.length === 1 ? refTypes[0] : refTypes.join(' & ');
+
+  return `Required<Pick<${baseType}, ${propsUnion}>>`;
+}
+
 function getMergedCompositeObjects(schema) {
   const { allOf, oneOf, anyOf, ...safeSchema } = schema;
   const composite = allOf || oneOf || anyOf || [];
   const subSchemas = composite.filter((v) => !('$ref' in v));
 
-  // This is the case where schema itself is of type object, with properties
-  // and at the same time has sub-schemas like `allOf` or similar
-  if (safeSchema.type === 'object' && 'properties' in safeSchema) {
+  // This is the case where schema itself has properties, required fields,
+  // or is of type object — and at the same time has sub-schemas like `allOf` or similar.
+  // We include the parent schema data so that `required` and `properties` are not lost.
+  if ('properties' in safeSchema || 'required' in safeSchema) {
     subSchemas.push(safeSchema);
   }
 

package/dist/index.js

@@ -41,7 +41,9 @@ function gen(spec, options) {
   return _gen2.default.call(void 0, spec, options);
 }
 
- async function applyConfigFile(options) {
+ async function applyConfigFile(
+  options
+) {
   try {
     if (!options.config) {
       return prepareAppOptions(options );
@@ -84,6 +86,7 @@ function readFile(filePath) {
     mode,
     schemaStyle,
     enumStyle,
+    enumNamesStyle,
     nullables,
     template,
     queryParamsSerialization = {},
@@ -108,6 +111,15 @@ function readFile(filePath) {
       _nullishCoalesce(_nullishCoalesce(schemaStyle, () => ( rest.schemaDeclarationStyle)), () => ( _swagger.APP_DEFAULTS.schemaDeclarationStyle)),
     enumDeclarationStyle:
       _nullishCoalesce(_nullishCoalesce(enumStyle, () => ( rest.enumDeclarationStyle)), () => ( _swagger.APP_DEFAULTS.enumDeclarationStyle)),
+    enumNamesStyle: normalizeEnumNamesStyle(enumNamesStyle),
     queryParamsSerialization: mergedQueryParamsSerialization,
   };
 } exports.prepareAppOptions = prepareAppOptions;
+
+function normalizeEnumNamesStyle(value) {
+  if (!value) return _swagger.APP_DEFAULTS.enumNamesStyle;
+  const lower = value.toLowerCase();
+  if (lower === 'pascal' || lower === 'pascalcase') return 'PascalCase';
+  if (lower === 'original') return 'original';
+  return _swagger.APP_DEFAULTS.enumNamesStyle;
+}

package/dist/swagger/typesExtractor.js

@@ -375,6 +375,7 @@ function isRequiredOnlyCompositeBranch(schema) {
   generationMode: 'full',
   schemaDeclarationStyle: 'interface',
   enumDeclarationStyle: 'union',
+  enumNamesStyle: 'original',
   queryParamsSerialization: {
     allowDots: true,
     arrayFormat: 'repeat',
@@ -395,6 +396,7 @@ function isRequiredOnlyCompositeBranch(schema) {
     generationMode: _nullishCoalesce(opts.generationMode, () => ( exports.APP_DEFAULTS.generationMode)),
     schemaDeclarationStyle: _nullishCoalesce(opts.schemaDeclarationStyle, () => ( exports.APP_DEFAULTS.schemaDeclarationStyle)),
     enumDeclarationStyle: _nullishCoalesce(opts.enumDeclarationStyle, () => ( exports.APP_DEFAULTS.enumDeclarationStyle)),
+    enumNamesStyle: _nullishCoalesce(opts.enumNamesStyle, () => ( exports.APP_DEFAULTS.enumNamesStyle)),
     queryParamsSerialization: {
       ...exports.APP_DEFAULTS.queryParamsSerialization,
       ...opts.queryParamsSerialization,

package/dist/types.d.ts

@@ -35,6 +35,13 @@ export interface ClientOptions {
     schemaDeclarationStyle?: SchemaDeclarationStyle;
     /** Controls whether plain string enums are emitted as unions or TypeScript enums */
     enumDeclarationStyle?: EnumDeclarationStyle;
+    /**
+     * Controls how enum member names are formatted when generating TypeScript `enum` declarations.
+     * Only applies when `enumDeclarationStyle` is set to `'enum'`.
+     * - `'original'` — use the raw enum value as the member name (e.g. `org name = "org name"`)
+     * - `'PascalCase'` — convert values to PascalCase (e.g. `OrgName = "org name"`)
+     */
+    enumNamesStyle?: EnumNamesStyle;
     /** Offers ability to adjust the OpenAPI spec before it is processed */
     modifiers?: {
         /** Global-level modifiers for parameter with a given name */
@@ -43,12 +50,14 @@ export interface ClientOptions {
         };
     };
 }
-export interface CliOptions extends FullAppOptions {
+export interface CliOptions extends Omit<FullAppOptions, 'enumNamesStyle'> {
     allowDots?: boolean;
     arrayFormat?: ArrayFormat;
     mode?: GenerationMode;
     schemaStyle?: SchemaDeclarationStyle;
     enumStyle?: EnumDeclarationStyle;
+    /** Accepts 'original', 'PascalCase', or 'pascal' (normalized to 'PascalCase') */
+    enumNamesStyle?: string;
     nullables?: NullableStrategy;
 }
 export interface FullAppOptions extends ClientOptions {
@@ -63,6 +72,7 @@ export type NullableStrategy = 'include' | 'nullableAsOptional' | 'ignore';
 export type GenerationMode = 'full' | 'schemas';
 export type SchemaDeclarationStyle = 'interface' | 'type';
 export type EnumDeclarationStyle = 'union' | 'enum';
+export type EnumNamesStyle = 'original' | 'PascalCase';
 /**
  * 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
@@ -75,6 +85,7 @@ export interface AppOptions extends ClientOptions {
     generationMode: GenerationMode;
     schemaDeclarationStyle: SchemaDeclarationStyle;
     enumDeclarationStyle: EnumDeclarationStyle;
+    enumNamesStyle: EnumNamesStyle;
     queryParamsSerialization: {
         allowDots: boolean;
         arrayFormat: ArrayFormat;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swaggie",
-  "version": "1.8.4",
+  "version": "1.8.6",
   "description": "Generate a fully typed TypeScript API client from your OpenAPI 3 spec",
   "author": {
     "name": "Piotr Dabrowski",
@@ -80,6 +80,7 @@
     "openapi-types": "^12.1.3",
     "sucrase": "3.35.1",
     "typescript": "5.9.3",
-    "vitepress": "^2.0.0-alpha.16"
+    "vitepress": "^2.0.0-alpha.16",
+    "vitepress-plugin-tabs": "0.8.0"
   }
 }