swaggie 1.8.5 → 1.8.7

package/README.md

@@ -12,7 +12,7 @@
 
 Swaggie generates TypeScript client code from an OpenAPI 3 specification. Instead of writing API-fetching code by hand, you point Swaggie at your API spec and it outputs a fully typed, ready-to-use client — helping you catch errors at compile time rather than at runtime.
 
-See the [Example section](#example) for a quick demo.
+See the [Example section](#example) for a quick demo, or visit the full documentation at **[yhnavein.github.io/swaggie](https://yhnavein.github.io/swaggie/)** for guides, configuration reference, and an interactive playground.
 
 > Inspired by [OpenApi Client](https://github.com/mikestead/openapi-client).
 
@@ -81,6 +81,7 @@ swaggie -s https://petstore3.swagger.io/api/v3/openapi.json -o ./client/petstore
 -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")
+    --enumNamesStyle <s>   Enum member name casing: "original" or "PascalCase" (default: "original")
     --dateFormat <format>  Date handling in schemas: "Date" or "string"
     --nullables <strategy> Nullable handling: "include", "nullableAsOptional", or "ignore"
     --preferAny            Use "any" instead of "unknown" for untyped values (default: false)
@@ -127,6 +128,7 @@ swaggie -c swaggie.config.json
   "generationMode": "full",
   "schemaDeclarationStyle": "interface",
   "enumDeclarationStyle": "union",
+  "enumNamesStyle": "original",
   "queryParamsSerialization": {
     "arrayFormat": "repeat",
     "allowDots": true
@@ -291,6 +293,30 @@ Use `enumDeclarationStyle` (or CLI `--enumStyle`) for plain string enums:
 
 Note: this applies only to plain string enums. Non-string enums are still emitted as union types.
 
+### Enum Names Style
+
+Use `enumNamesStyle` (or CLI `--enumNamesStyle`) to control the casing of enum member names when `enumDeclarationStyle` is `"enum"`:
+- `"original"` (default): member names are used exactly as they appear in the spec
+- `"PascalCase"`: member names are converted to PascalCase
+
+### `x-ts-type` Extension
+
+Add `x-ts-type` to any schema in your spec to emit a verbatim TypeScript type string instead of deriving it from the schema definition. This is useful for intersection types, complex mapped types, or any TypeScript construct that cannot be expressed in OpenAPI's type system:
+
+```yaml
+ResourceAccess:
+  x-ts-type: >-
+    { items?: { [key: string]: Entry } } & { [key: string]: boolean | Entry | undefined }
+  type: object   # kept for doc/validation purposes
+```
+
+Swaggie emits exactly:
+```typescript
+export type ResourceAccess = { items?: { [key: string]: Entry } } & { [key: string]: boolean | Entry | undefined };
+```
+
+`x-ts-type` takes precedence over all other schema fields, including `$ref`. See the [full documentation](https://yhnavein.github.io/swaggie/guide/advanced#x-ts-type-extension) for more detail.
+
 ### 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.
@@ -358,15 +384,6 @@ function error(e) {
 
 ---
 
-## Server Setup Samples
-
-Swaggie only needs a JSON or YAML OpenAPI spec file — it does not require a running server. However, if you want to see how to configure your backend to expose an OpenAPI spec automatically, check out the sample configurations in the `samples/` folder:
-
-- [ASP.NET Core + NSwag](./samples/dotnetcore/nswag/README.md)
-- [ASP.NET Core + Swashbuckle](./samples/dotnetcore/swashbuckle/README.md)
-
----
-
 ## What's Supported
 
 | Supported                                                                      | Not Supported                                        |
@@ -374,7 +391,7 @@ Swaggie only needs a JSON or YAML OpenAPI spec file — it does not require a ru
 | OpenAPI 3.0, 3.1, 3.2                                                          | Swagger / OpenAPI 2.0                                |
 | `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)     |
+| Extensions: `x-position`, `x-name`, `x-enumNames`, `x-enum-varnames`, `x-ts-type` | 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` | OpenAPI callbacks and webhooks                       |
 | Various enum definition styles, support for additionalProperties               |                                                      |

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

@@ -53,6 +53,18 @@ function renderSchema(
     return '';
   }
 
+  // x-ts-type takes precedence over everything, including $ref.
+  // When present, emit the literal TypeScript type string verbatim.
+  if ('x-ts-type' in schema) {
+    const result = [];
+    const s = schema ;
+    if (_nullishCoalesce(s.description, () => ( s.title))) {
+      result.push(_jsDocs.renderComment.call(void 0, _nullishCoalesce(s.description, () => ( s.title))));
+    }
+    result.push(`export type ${safeName} = ${schema['x-ts-type']};`);
+    return result.join('\n');
+  }
+
   // This is an interesting case, because it is allowed but not likely to be used
   // as it is just a reference to another schema object
   if ('$ref' in schema) {
@@ -201,7 +213,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(' | ');
@@ -218,17 +230,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.
  */

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.5",
+  "version": "1.8.7",
   "description": "Generate a fully typed TypeScript API client from your OpenAPI 3 spec",
   "author": {
     "name": "Piotr Dabrowski",