swagger-typescript-api 10.0.3 → 11.0.0--alpha

package/README.md

@@ -71,6 +71,8 @@ Options:
   --clean-output                clean output folder before generate api. WARNING: May cause data loss (default: false)
   --api-class-name <string>     name of the api class
   --patch                       fix up small errors in the swagger source definition (default: false)
+  --debug                       additional information about processes inside this tool (default: false)
+  --another-array-type          generate array types as Array<Type> (by default Type[]) (default: false)
   -h, --help                    display help for command
 ```
 
@@ -122,6 +124,17 @@ generateApi({
   generateUnionEnums: false,
   addReadonly: false,
   extraTemplates: [],
+  anotherArrayType: false, 
+  codeGenConstructs: (constructs) => ({
+    ...constructs,
+    RecordType: (key, value) => `MyRecord<key, value>`
+  }),
+  primitiveTypeConstructs: (constructs) => ({
+      ...constructs,
+      string: {
+        'date-time': 'Date'
+      }
+  }),
   hooks: {
     onCreateComponent: (component) => {},
     onCreateRequestParams: (rawType) => {},
@@ -203,8 +216,213 @@ When we change it to `--module-name-index 1` then Api class have two properties
 This option will group your API operations based on their first tag - mirroring how the Swagger UI groups displayed operations
 
 
+## Modification internal codegen structs with NodeJS API:  
+
+You are able to modify TypeScript internal structs using for generating output with using `generateApi` options `codeGenConstructs` and `primitiveTypeConstructs`.  
+
+### `codeGenConstructs`  
+
+This option has type `(struct: CodeGenConstruct) => Partial<CodeGenConstruct>`.
+
+```ts
+generateApi({
+  // ...
+  codeGenConstructs: (struct) => ({
+      Keyword: {
+          Number: "number",
+          String: "string",
+          Boolean: "boolean",
+          Any: "any",
+          Void: "void",
+          Unknown: "unknown",
+          Null: "null",
+          Undefined: "undefined",
+          Object: "object",
+          File: "File",
+          Date: "Date",
+          Type: "type",
+          Enum: "enum",
+          Interface: "interface",
+          Array: "Array",
+          Record: "Record",
+          Intersection: "&",
+          Union: "|",
+      },
+      CodeGenKeyword: {
+          UtilRequiredKeys: "UtilRequiredKeys",
+      },
+      /**
+       * $A[] or Array<$A>
+       */
+      ArrayType: (content) => {
+          if (this.anotherArrayType) {
+              return `Array<${content}>`;
+          }
+
+          return `(${content})[]`;
+      },
+      /**
+       * "$A"
+       */
+      StringValue: (content) => `"${content}"`,
+      /**
+       * $A
+       */
+      BooleanValue: (content) => `${content}`,
+      /**
+       * $A
+       */
+      NumberValue: (content) => `${content}`,
+      /**
+       * $A
+       */
+      NullValue: (content) => content,
+      /**
+       * $A1 | $A2
+       */
+      UnionType: (contents) => _.join(_.uniq(contents), ` | `),
+      /**
+       * ($A1)
+       */
+      ExpressionGroup: (content) => (content ? `(${content})` : ""),
+      /**
+       * $A1 & $A2
+       */
+      IntersectionType: (contents) => _.join(_.uniq(contents), ` & `),
+      /**
+       * Record<$A1, $A2>
+       */
+      RecordType: (key, value) => `Record<${key}, ${value}>`,
+      /**
+       * readonly $key?:$value
+       */
+      TypeField: ({ readonly, key, optional, value }) =>
+          _.compact([readonly && "readonly ", key, optional && "?", ": ", value]).join(""),
+      /**
+       * [key: $A1]: $A2
+       */
+      InterfaceDynamicField: (key, value) => `[key: ${key}]: ${value}`,
+      /**
+       * $A1 = $A2
+       */
+      EnumField: (key, value) => `${key} = ${value}`,
+      /**
+       * $A0.key = $A0.value,
+       * $A1.key = $A1.value,
+       * $AN.key = $AN.value,
+       */
+      EnumFieldsWrapper: (contents) =>
+          _.map(contents, ({ key, value }) => `  ${key} = ${value}`).join(",\n"),
+      /**
+       * {\n $A \n}
+       */
+      ObjectWrapper: (content) => `{\n${content}\n}`,
+      /**
+       * /** $A *\/
+       */
+      MultilineComment: (contents, formatFn) =>
+          [
+              ...(contents.length === 1
+                  ? [`/** ${contents[0]} */`]
+                  : ["/**", ...contents.map((content) => ` * ${content}`), " */"]),
+          ].map((part) => `${formatFn ? formatFn(part) : part}\n`),
+      /**
+       * $A1<...$A2.join(,)>
+       */
+      TypeWithGeneric: (typeName, genericArgs) => {
+          return `${typeName}${genericArgs.length ? `<${genericArgs.join(",")}>` : ""}`;
+      },
+  })
+})
+```  
+
+For example, if you need to generate output `Record<string, any>` instead of `object` you can do it with using following code:  
+
+```ts
+generateApi({
+    // ...
+    codeGenConstructs: (struct) => ({
+        Keyword: {
+            Object: "Record<string, any>",
+        }
+    })
+})
+```
+
+### `primitiveTypeConstructs`  
+
+It is type mapper or translator swagger schema objects. `primitiveTypeConstructs` translates `type`/`format` schema fields to typescript structs.  
+This option has type  
+```ts
+type PrimitiveTypeStructValue =
+  | string
+  | ((schema: Record<string, any>, parser: import("./src/schema-parser/schema-parser").SchemaParser) => string);
+
+type PrimitiveTypeStruct = Record<
+  "integer" | "number" | "boolean" | "object" | "file" | "string" | "array",
+  string | ({ $default: PrimitiveTypeStructValue } & Record<string, PrimitiveTypeStructValue>)
+>
+
+declare const primitiveTypeConstructs: (struct: PrimitiveTypeStruct) => Partial<PrimitiveTypeStruct>
+
+generateApi({
+    // ...
+    primitiveTypeConstructs: (struct) => ({
+        integer: () => "number",
+        number: () => "number",
+        boolean: () => "boolean",
+        object: () => "object",
+        file: () => "File",
+        string: {
+            $default: () => "string",
+
+            /** formats */
+            binary: () => "File",
+            file: () => "File",
+            "date-time": () => "string",
+            time: () => "string",
+            date: () => "string",
+            duration: () => "string",
+            email: () => "string",
+            "idn-email": () => "string",
+            "idn-hostname": () => "string",
+            ipv4: () => "string",
+            ipv6: () => "string",
+            uuid: () => "string",
+            uri: () => "string",
+            "uri-reference": () => "string",
+            "uri-template": () => "string",
+            "json-pointer": () => "string",
+            "relative-json-pointer": () => "string",
+            regex: () => "string",
+        },
+        array: (schema, parser) => {
+            const content = parser.getInlineParseContent(schema.items);
+            return parser.checkAndAddNull(schema, `(${content})[]`);
+        },
+    })
+})
+```
+
+For example, if you need to change `"string"/"date-time"` default output as `string` to `Date` you can do it with using following code:  
+
+```ts
+
+generateApi({
+    primitiveTypeConstructs: (struct) => ({
+        string: {
+            "date-time": "Date",
+        },
+    })
+})
+
+```
+
+See more about [swagger schema type/format data here](https://json-schema.org/understanding-json-schema/reference/string.html#dates-and-times)  
+
 ## 📄 Mass media  
 
+- [5 Lessons learned about swagger-typescript-api](https://christo8989.medium.com/5-lessons-learned-about-swagger-typescript-api-511240b34c1)  
 - [Why Swagger schemes are needed in frontend development ?](https://dev.to/js2me/why-swagger-schemes-are-needed-in-frontend-development-2cb4)  
 - [Migration en douceur vers TypeScript (French)](https://www.premieroctet.com/blog/migration-typescript/)  
 - [swagger-typescript-api usage (Japanese)](https://zenn.dev/watahaya/articles/2f4a716c47903b)   

package/index.d.ts

@@ -127,8 +127,63 @@ interface GenerateApiParamsBase {
    * generate readonly properties (default: false)
    */
   addReadonly?: boolean;
+
+  primitiveTypeConstructs?: (struct: PrimitiveTypeStruct) => Partial<PrimitiveTypeStruct>;
+
+  codeGenConstructs?: (struct: CodeGenConstruct) => Partial<CodeGenConstruct>;
 }
 
+type CodeGenConstruct = {
+  Keyword: {
+    Number: string;
+    String: string;
+    Boolean: string;
+    Any: string;
+    Void: string;
+    Unknown: string;
+    Null: string;
+    Undefined: string;
+    Object: string;
+    File: string;
+    Date: string;
+    Type: string;
+    Enum: string;
+    Interface: string;
+    Array: string;
+    Record: string;
+    Intersection: string;
+    Union: string;
+  };
+  CodeGenKeyword: {
+    UtilRequiredKeys: string;
+  };
+  ArrayType: (content: any) => string;
+  StringValue: (content: any) => string;
+  BooleanValue: (content: any) => string;
+  NumberValue: (content: any) => string;
+  NullValue: (content: any) => string;
+  UnionType: (content: any) => string;
+  ExpressionGroup: (content: any) => string;
+  IntersectionType: (content: any) => string;
+  RecordType: (content: any) => string;
+  TypeField: (content: any) => string;
+  InterfaceDynamicField: (content: any) => string;
+  EnumField: (content: any) => string;
+  EnumFieldsWrapper: (content: any) => string;
+  ObjectWrapper: (content: any) => string;
+  MultilineComment: (content: any) => string;
+  TypeWithGeneric: (content: any) => string;
+};
+
+type PrimitiveTypeStructValue =
+  | string
+  | ((schema: Record<string, any>, parser: import("./src/schema-parser/schema-parser").SchemaParser) => string);
+
+type PrimitiveTypeStruct = Record<
+  "integer" | "number" | "boolean" | "object" | "file" | "string" | "array",
+  string | ({ $default: PrimitiveTypeStructValue } & Record<string, PrimitiveTypeStructValue>)
+>;
+
 interface GenerateApiParamsFromPath extends GenerateApiParamsBase {
   /**
    * path to swagger schema
@@ -324,6 +379,12 @@ export interface GenerateApiConfiguration {
     hasDescription: boolean;
   };
   config: {
+    input: string;
+    output: string;
+    url: string;
+    spec: any;
+    fileName: string;
+    authorizationToken?: string;
     generateResponses: boolean;
     defaultResponseAsSuccess: boolean;
     generateRouteTypes: boolean;
@@ -335,10 +396,35 @@ export interface GenerateApiConfiguration {
     convertedFromSwagger2: boolean;
     moduleNameIndex: number;
     moduleNameFirstTag: boolean;
+    extraTemplates: { name: string; path: string }[];
     disableStrictSSL: boolean;
     disableProxy: boolean;
     extractRequestParams: boolean;
     unwrapResponseData: boolean;
+    sortTypes: boolean;
+    singleHttpClient: boolean;
+    typePrefix: string;
+    typeSuffix: string;
+    patch: boolean;
+    cleanOutput: boolean;
+    debug: boolean;
+    anotherArrayType: boolean;
+    extractRequestBody: boolean;
+    httpClientType: "axios" | "fetch";
+    addReadonly: boolean;
+    extractResponseBody: boolean;
+    extractResponseError: boolean;
+    defaultResponseType: boolean;
+    toJS: boolean;
+    disableThrowOnError: boolean;
+    silent: boolean;
+    hooks: Hooks;
+    enumNamesAsValues: boolean;
+    version: string;
+    internalTemplateOptions: {
+      addUtilRequiredKeysType: boolean;
+    };
+    componentTypeNameResolver: typeof import("./src/util/name-resolver").ComponentTypeNameResolver;
     fileNames: {
       dataContracts: string;
       routeTypes: string;
@@ -351,6 +437,11 @@ export interface GenerateApiConfiguration {
       httpClient: string;
       routeTypes: string;
       routeName: string;
+      dataContractJsDoc: string;
+      interfaceDataContract: string;
+      typeDataContract: string;
+      enumDataContract: string;
+      objectFieldJsDoc: string;
     };
     routeNameDuplicatesMap: Map<string, string>;
     apiClassName: string;
@@ -371,7 +462,9 @@ export interface GenerateApiConfiguration {
   utils: {
     formatDescription: (description: string, inline?: boolean) => string;
     internalCase: (value: string) => string;
+    /** @deprecated */
     classNameCase: (value: string) => string;
+    pascalCase: (value: string) => string;
     getInlineParseContent: (rawTypeData: SchemaComponent["rawTypeData"], typeName?: string) => string;
     getParseContent: (rawTypeData: SchemaComponent["rawTypeData"], typeName?: string) => ModelType;
     getComponentByRef: (ref: string) => SchemaComponent;