swaggie 1.5.2 → 1.5.3-beta.2

package/README.md

@@ -103,6 +103,7 @@ Sample configuration looks like this:
   "preferAny": true,
   "servicePrefix": "",
   "dateFormat": "Date", // "string" | "Date"
+  "nullableStrategy": "ignore", // "ignore" | "include" | "nullableAsOptional"
   "queryParamsSerialization": {
     "arrayFormat": "repeat", // "repeat" | "brackets" | "indices"
     "allowDots": true
@@ -162,6 +163,24 @@ Once you know what your backend expects, you can adjust the configuration file a
 }
 ```
 
+### Nullable Strategy
+
+OpenAPI 3.0 allows marking fields as `nullable: true`. Swaggie provides three strategies for translating this into TypeScript, controlled by the `nullableStrategy` option:
+
+| Value                  | Description                                                                        |
+| ---------------------- | ---------------------------------------------------------------------------------- |
+| `"ignore"` (default)   | `nullable: true` is ignored. Types are generated as if `nullable` was not set.     |
+| `"include"`            | `nullable: true` appends `\| null` to the TypeScript type (e.g. `string \| null`). |
+| `"nullableAsOptional"` | `nullable: true` makes the property optional (`?`) instead of adding `\| null`.    |
+
+**Examples** for a schema with `tenant: { type: 'string', nullable: true }` (required):
+
+```typescript
+// nullableStrategy: "ignore"   →  tenant: string;
+// nullableStrategy: "include"  →  tenant: string | null;
+// nullableStrategy: "nullableAsOptional"  →  tenant?: string;
+```
+
 ### Code Quality
 
 > Please note that it's **recommended** to pipe Swaggie command to some prettifier like `prettier`, `biome` or `dprint` to make the generated code look not only nice, but also persistent.
@@ -301,7 +320,7 @@ function error(e) {
 | Content types: `JSON`, `text`, `multipart/form-data`                           | Multiple request types (only one will be used)  |
 | Content types: `application/x-www-form-urlencoded`, `application/octet-stream` | References to other spec files                  |
 | Different types of enum definitions (+ OpenAPI 3.1 support for enums)          | OpenAPI callbacks                               |
-| Paths inheritance, comments (descriptions)                                     | OpenAPI webhooks                                |
+| Paths inheritance, comments (descriptions), nullable                           | OpenAPI webhooks                                |
 | Getting documents from remote locations or as path reference (local file)      |                                                 |
 | Grouping endpoints by tags + handle gracefully duplicate operation ids         |                                                 |
 

package/dist/gen/genOperations.js

@@ -98,7 +98,7 @@ function prepareClient(
     const [respObject, responseContentType] = _utils.getBestResponse.call(void 0, op);
     const returnType = _swagger.getParameterType.call(void 0, respObject, options);
 
-    const body = getRequestBody(op.requestBody);
+    const body = getRequestBody(op.requestBody, options);
     const queryParams = getParams(op.parameters , options, ['query']);
     const params = getParams(op.parameters , options);
 
@@ -278,7 +278,10 @@ function prepareUrl(path) {
   );
 } exports.getParamName = getParamName;
 
-function getRequestBody(reqBody) {
+function getRequestBody(
+  reqBody,
+  options
+) {
   if (reqBody && 'content' in reqBody) {
     const [bodyContent, contentType] = _utils.getBestContentType.call(void 0, reqBody);
     const isFormData = contentType === 'form-data';
@@ -287,7 +290,7 @@ function getRequestBody(reqBody) {
       return {
         originalName: _nullishCoalesce(reqBody['x-name'], () => ( 'body')),
         name: getParamName(_nullishCoalesce(reqBody['x-name'], () => ( 'body'))),
-        type: isFormData ? 'FormData' : _swagger.getParameterType.call(void 0, bodyContent, {}),
+        type: isFormData ? 'FormData' : _swagger.getParameterType.call(void 0, bodyContent, options),
         optional: !reqBody.required,
         original: reqBody,
         contentType,

package/dist/gen/genTypes.js

@@ -200,7 +200,14 @@ function renderTypeProp(
   if ('description' in definition || 'title' in definition) {
     lines.push(_jsDocs.renderComment.call(void 0, _nullishCoalesce(definition.description, () => ( definition.title))));
   }
-  const optionalMark = required ? '' : '?';
+
+  // When nullableAsOptional strategy is set, nullable properties are treated as optional
+  const isNullableAsOptional =
+    options.nullableStrategy === 'nullableAsOptional' &&
+    !('$ref' in definition) &&
+    (definition ).nullable === true;
+  const isOptional = !required || isNullableAsOptional;
+  const optionalMark = isOptional ? '?' : '';
   // If prop name is not a valid identifier, we need to wrap it in quotes.
   // We can't use getSafeIdentifier here because it will affect the data model.
   const safePropName = _utils.escapePropName.call(void 0, propName);

package/dist/swagger/typesExtractor.js

@@ -1,4 +1,4 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
 
 var _utils = require('../utils');
 
@@ -48,25 +48,42 @@ var _utils = require('../utils');
     return getSafeIdentifier(refName) || unknownType;
   }
 
+  if (schema.type === 'null') {
+    return 'null';
+  }
+
+  const isNullable = 'nullable' in schema && schema.nullable === true;
+  const strategy = _nullishCoalesce(options.nullableStrategy, () => ( 'ignore'));
+  const isNullableSuffix = isNullable && strategy === 'include' ? ' | null' : '';
+  const type = getTypeFromSchemaInternal(schema, options);
+
+  if (isNullableSuffix && type.endsWith('| null')) {
+    return type;
+  }
+  return type + isNullableSuffix;
+} exports.getTypeFromSchema = getTypeFromSchema;
+
+function getTypeFromSchemaInternal(
+  schema,
+  options
+) {
+  const unknownType = options.preferAny ? 'any' : 'unknown';
+
   if ('allOf' in schema || 'oneOf' in schema || 'anyOf' in schema) {
     return getTypeFromComposites(schema , options);
   }
 
   if (schema.type === 'array') {
     if (schema.items) {
-      return `${getTypeFromSchema(schema.items, options)}[]`;
+      return `${getNestedTypeFromSchema(schema.items, options)}[]`;
     }
     return `${unknownType}[]`;
   }
   if (schema.type === 'object') {
     return getTypeFromObject(schema, options);
   }
-  if (schema.type === 'null') {
-    return 'null';
-  }
-
   if ('enum' in schema) {
-    return `(${schema.enum.map((v) => JSON.stringify(v)).join(' | ')})`;
+    return `${schema.enum.map((v) => JSON.stringify(v)).join(' | ')}`;
   }
   if (schema.type === 'integer' || schema.type === 'number') {
     return 'number';
@@ -81,7 +98,20 @@ var _utils = require('../utils');
     return 'boolean';
   }
   return unknownType;
-} exports.getTypeFromSchema = getTypeFromSchema;
+}
+
+function getNestedTypeFromSchema(
+  schema,
+  options
+) {
+  const strategy = _nullishCoalesce(options.nullableStrategy, () => ( 'ignore'));
+  const isNullableAndActive =
+    'nullable' in schema && schema.nullable === true && strategy === 'include';
+  if (isNullableAndActive || ('enum' in schema && schema.enum)) {
+    return `(${getTypeFromSchema(schema, options)})`;
+  }
+  return getTypeFromSchema(schema, options);
+}
 
 /**
  * Knowing that the schema is an object, this function returns a TypeScript type definition

package/dist/types.d.ts

@@ -20,6 +20,13 @@ export interface ClientOptions {
     servicePrefix?: string;
     /** How date should be handled. It does not do any special serialization */
     dateFormat?: DateSupport;
+    /**
+     * Controls how OpenAPI 'nullable' is translated into TypeScript types. Default: 'ignore'.
+     * 'include' - 'nullable: true' appends `| null` to the TypeScript type (e.g. `string | null`).
+     * 'nullableAsOptional' - 'nullable: true' makes the property optional (`?`) instead of adding `| null`.
+     * 'ignore' - 'nullable: true' is ignored.
+     */
+    nullableStrategy?: NullableStrategy;
     /** Options for query parameters serialization */
     queryParamsSerialization: QueryParamsSerializationOptions;
     /** Offers ability to adjust the OpenAPI spec before it is processed */
@@ -42,6 +49,7 @@ export type Template = 'axios' | 'fetch' | 'ng1' | 'ng2' | 'swr-axios' | 'xior'
 export type HttpMethod = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch';
 export type DateSupport = 'string' | 'Date';
 export type ArrayFormat = 'indices' | 'repeat' | 'brackets';
+export type NullableStrategy = 'include' | 'nullableAsOptional' | 'ignore';
 /**
  * Local type that represent Operation as understood by Swaggie
  **/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swaggie",
-  "version": "1.5.2",
+  "version": "1.5.3-beta.2",
   "description": "Generate TypeScript REST client code from an OpenAPI spec",
   "author": {
     "name": "Piotr Dabrowski",
@@ -10,7 +10,7 @@
   "homepage": "https://github.com/yhnavein/swaggie",
   "repository": {
     "type": "git",
-    "url": "https://github.com/yhnavein/swaggie.git"
+    "url": "git+https://github.com/yhnavein/swaggie.git"
   },
   "bugs": {
     "url": "https://github.com/yhnavein/swaggie/issues"