@kubb/swagger-ts 1.15.0-canary.20231112T135108 → 2.0.0-alpha.10

package/src/generators/TypeGenerator.ts

@@ -0,0 +1,378 @@
+import { SchemaGenerator } from '@kubb/core'
+import { getUniqueName } from '@kubb/core/utils'
+import * as factory from '@kubb/parser/factory'
+import { isReference } from '@kubb/swagger/utils'
+
+import { camelCase } from 'change-case'
+
+import type { PluginContext } from '@kubb/core'
+import type { ts } from '@kubb/parser'
+import type { OpenAPIV3, Refs } from '@kubb/swagger'
+import type { Options as CaseOptions } from 'change-case'
+
+// based on https://github.com/cellular/oazapfts/blob/7ba226ebb15374e8483cc53e7532f1663179a22c/src/codegen/generate.ts#L398
+
+type Options = {
+  usedEnumNames: Record<string, number>
+
+  withJSDocs?: boolean
+  resolveName: PluginContext['resolveName']
+  enumType: 'enum' | 'asConst' | 'asPascalConst'
+  dateType: 'string' | 'date'
+  optionalType: 'questionToken' | 'undefined' | 'questionTokenAndUndefined'
+}
+export class TypeGenerator extends SchemaGenerator<Options, OpenAPIV3.SchemaObject, ts.Node[]> {
+  refs: Refs = {}
+
+  extraNodes: ts.Node[] = []
+
+  aliases: ts.TypeAliasDeclaration[] = []
+
+  // Keep track of already used type aliases
+  #usedAliasNames: Record<string, number> = {}
+
+  #caseOptions: CaseOptions = {
+    delimiter: '',
+    stripRegexp: /[^A-Z0-9$]/gi,
+  }
+
+  constructor(
+    options: Options = {
+      usedEnumNames: {},
+      withJSDocs: true,
+      resolveName: ({ name }) => name,
+      enumType: 'asConst',
+      dateType: 'string',
+      optionalType: 'questionToken',
+    },
+  ) {
+    super(options)
+
+    return this
+  }
+
+  build({
+    schema,
+    baseName,
+    description,
+    keysToOmit,
+  }: {
+    schema: OpenAPIV3.SchemaObject
+    baseName: string
+    description?: string
+    keysToOmit?: string[]
+  }): ts.Node[] {
+    const nodes: ts.Node[] = []
+    const type = this.#getTypeFromSchema(schema, baseName)
+
+    if (!type) {
+      return this.extraNodes
+    }
+
+    const node = factory.createTypeAliasDeclaration({
+      modifiers: [factory.modifiers.export],
+      name: this.options.resolveName({ name: baseName }) || baseName,
+      type: keysToOmit?.length ? factory.createOmitDeclaration({ keys: keysToOmit, type, nonNullable: true }) : type,
+    })
+
+    if (description) {
+      nodes.push(
+        factory.appendJSDocToNode({
+          node,
+          comments: [`@description ${description}`],
+        }),
+      )
+    } else {
+      nodes.push(node)
+    }
+
+    // filter out if the export name is the same as one that we already defined in extraNodes(see enum)
+    const filterdNodes = nodes.filter(
+      (node: ts.Node) =>
+        !this.extraNodes.some(
+          (extraNode: ts.Node) => (extraNode as ts.TypeAliasDeclaration)?.name?.escapedText === (node as ts.TypeAliasDeclaration)?.name?.escapedText,
+        ),
+    )
+
+    return [...this.extraNodes, ...filterdNodes]
+  }
+
+  /**
+   * Creates a type node from a given schema.
+   * Delegates to getBaseTypeFromSchema internally and
+   * optionally adds a union with null.
+   */
+  #getTypeFromSchema(schema?: OpenAPIV3.SchemaObject, name?: string): ts.TypeNode | null {
+    const type = this.#getBaseTypeFromSchema(schema, name)
+
+    if (!type) {
+      return null
+    }
+
+    if (schema && !schema.nullable) {
+      return type
+    }
+
+    return factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.null] })
+  }
+
+  /**
+   * Recursively creates a type literal with the given props.
+   */
+  #getTypeFromProperties(baseSchema?: OpenAPIV3.SchemaObject, baseName?: string) {
+    const { optionalType } = this.options
+    const properties = baseSchema?.properties || {}
+    const required = baseSchema?.required
+    const additionalProperties = baseSchema?.additionalProperties
+
+    const members: Array<ts.TypeElement | null> = Object.keys(properties).map((name) => {
+      const schema = properties[name] as OpenAPIV3.SchemaObject
+
+      const isRequired = required && required.includes(name)
+      let type = this.#getTypeFromSchema(schema, this.options.resolveName({ name: `${baseName || ''} ${name}` }))
+
+      if (!type) {
+        return null
+      }
+
+      if (!isRequired && ['undefined', 'questionTokenAndUndefined'].includes(optionalType)) {
+        type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.undefined] })
+      }
+      const propertySignature = factory.createPropertySignature({
+        questionToken: ['questionToken', 'questionTokenAndUndefined'].includes(optionalType) && !isRequired,
+        name,
+        type: type as ts.TypeNode,
+        readOnly: schema.readOnly,
+      })
+      if (this.options.withJSDocs) {
+        return factory.appendJSDocToNode({
+          node: propertySignature,
+          comments: [
+            schema.description ? `@description ${schema.description}` : undefined,
+            schema.type ? `@type ${schema.type}${isRequired ? '' : ' | undefined'} ${schema.format || ''}` : undefined,
+            schema.example ? `@example ${schema.example as string}` : undefined,
+            schema.deprecated ? `@deprecated` : undefined,
+            schema.default !== undefined && typeof schema.default === 'string' ? `@default '${schema.default}'` : undefined,
+            schema.default !== undefined && typeof schema.default !== 'string' ? `@default ${schema.default as string}` : undefined,
+          ].filter(Boolean),
+        })
+      }
+
+      return propertySignature
+    })
+    if (additionalProperties) {
+      const type = additionalProperties === true ? factory.keywordTypeNodes.any : this.#getTypeFromSchema(additionalProperties as OpenAPIV3.SchemaObject)
+
+      if (type) {
+        members.push(factory.createIndexSignature(type))
+      }
+    }
+    return factory.createTypeLiteralNode(members.filter(Boolean))
+  }
+
+  /**
+   * Create a type alias for the schema referenced by the given ReferenceObject
+   */
+  #getRefAlias(obj: OpenAPIV3.ReferenceObject, _baseName?: string) {
+    const { $ref } = obj
+    let ref = this.refs[$ref]
+
+    if (ref) {
+      return factory.createTypeReferenceNode(ref.propertyName, undefined)
+    }
+
+    const originalName = getUniqueName($ref.replace(/.+\//, ''), this.#usedAliasNames)
+    const propertyName = this.options.resolveName({ name: originalName }) || originalName
+
+    ref = this.refs[$ref] = {
+      propertyName,
+      originalName,
+    }
+
+    return factory.createTypeReferenceNode(ref.propertyName, undefined)
+  }
+
+  /**
+   * This is the very core of the OpenAPI to TS conversion - it takes a
+   * schema and returns the appropriate type.
+   */
+  #getBaseTypeFromSchema(schema: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined, baseName?: string): ts.TypeNode | null {
+    if (!schema) {
+      return factory.keywordTypeNodes.any
+    }
+
+    if (isReference(schema)) {
+      return this.#getRefAlias(schema, baseName)
+    }
+
+    if (schema.oneOf) {
+      // union
+      const schemaWithoutOneOf = { ...schema, oneOf: undefined }
+
+      const union = factory.createUnionDeclaration({
+        withParentheses: true,
+        nodes: schema.oneOf
+          .map((item: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject) => {
+            return this.#getBaseTypeFromSchema(item)
+          })
+          .filter((item) => {
+            return item && item !== factory.keywordTypeNodes.any
+          }) as Array<ts.TypeNode>,
+      })
+
+      if (schemaWithoutOneOf.properties) {
+        return factory.createIntersectionDeclaration({
+          nodes: [this.#getBaseTypeFromSchema(schemaWithoutOneOf, baseName), union].filter(Boolean),
+        })
+      }
+
+      return union
+    }
+
+    if (schema.anyOf) {
+      const schemaWithoutAnyOf = { ...schema, anyOf: undefined }
+
+      const union = factory.createUnionDeclaration({
+        withParentheses: true,
+        nodes: schema.anyOf
+          .map((item: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject) => {
+            return this.#getBaseTypeFromSchema(item)
+          })
+          .filter((item) => {
+            return item && item !== factory.keywordTypeNodes.any
+          }) as Array<ts.TypeNode>,
+      })
+
+      if (schemaWithoutAnyOf.properties) {
+        return factory.createIntersectionDeclaration({
+          nodes: [this.#getBaseTypeFromSchema(schemaWithoutAnyOf, baseName), union].filter(Boolean),
+        })
+      }
+
+      return union
+    }
+    if (schema.allOf) {
+      // intersection/add
+      const schemaWithoutAllOf = { ...schema, allOf: undefined }
+
+      const and = factory.createIntersectionDeclaration({
+        withParentheses: true,
+        nodes: schema.allOf
+          .map((item: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject) => {
+            return this.#getBaseTypeFromSchema(item)
+          })
+          .filter((item) => {
+            return item && item !== factory.keywordTypeNodes.any
+          }) as Array<ts.TypeNode>,
+      })
+
+      if (schemaWithoutAllOf.properties) {
+        return factory.createIntersectionDeclaration({
+          nodes: [this.#getBaseTypeFromSchema(schemaWithoutAllOf, baseName), and].filter(Boolean),
+        })
+      }
+
+      return and
+    }
+
+    /**
+     * Enum will be defined outside the baseType(hints the baseName check)
+     */
+    if (schema.enum && baseName) {
+      const enumName = getUniqueName(baseName, this.options.usedEnumNames)
+
+      let enums: [key: string, value: string | number][] = [...new Set(schema.enum)].map((key) => [key, key])
+
+      if ('x-enumNames' in schema) {
+        enums = [...new Set(schema['x-enumNames'] as string[])].map((key: string, index) => {
+          return [key, schema.enum?.[index]]
+        })
+      }
+
+      this.extraNodes.push(
+        ...factory.createEnumDeclaration({
+          name: camelCase(enumName, this.#caseOptions),
+          typeName: this.options.resolveName({ name: enumName }),
+          enums,
+          type: this.options.enumType,
+        }),
+      )
+      return factory.createTypeReferenceNode(this.options.resolveName({ name: enumName }), undefined)
+    }
+
+    if (schema.enum) {
+      return factory.createUnionDeclaration({
+        nodes: schema.enum.map((name: string) => {
+          return factory.createLiteralTypeNode(typeof name === 'number' ? factory.createNumericLiteral(name) : factory.createStringLiteral(`${name}`))
+        }) as unknown as Array<ts.TypeNode>,
+      })
+    }
+
+    if ('items' in schema) {
+      // items -> array
+      const node = this.#getTypeFromSchema(schema.items as OpenAPIV3.SchemaObject, baseName)
+      if (node) {
+        return factory.createArrayTypeNode(node)
+      }
+    }
+    /**
+     * OpenAPI 3.1
+     * @link https://json-schema.org/understanding-json-schema/reference/array.html#tuple-validation
+     */
+    if ('prefixItems' in schema) {
+      const prefixItems = schema.prefixItems as OpenAPIV3.SchemaObject[]
+
+      return factory.createTupleDeclaration({
+        nodes: prefixItems.map((item) => {
+          // no baseType so we can fall back on an union when using enum
+          return this.#getBaseTypeFromSchema(item, undefined)
+        }) as Array<ts.TypeNode>,
+      })
+    }
+
+    if (schema.properties || schema.additionalProperties) {
+      // properties -> literal type
+      return this.#getTypeFromProperties(schema, baseName)
+    }
+
+    if (schema.type) {
+      if (Array.isArray(schema.type)) {
+        // OPENAPI v3.1.0: https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0
+        const [type, nullable] = schema.type as Array<OpenAPIV3.NonArraySchemaObjectType>
+
+        return factory.createUnionDeclaration({
+          nodes: [
+            this.#getBaseTypeFromSchema(
+              {
+                ...schema,
+                type,
+              },
+              baseName,
+            ),
+            nullable ? factory.createLiteralTypeNode(factory.createNull()) : undefined,
+          ].filter(Boolean),
+        })
+      }
+
+      if (this.options.dateType === 'date' && ['date', 'date-time'].some((item) => item === schema.format)) {
+        return factory.createTypeReferenceNode(factory.createIdentifier('Date'))
+      }
+
+      // string, boolean, null, number
+      if (schema.type in factory.keywordTypeNodes) {
+        return factory.keywordTypeNodes[schema.type as keyof typeof factory.keywordTypeNodes]
+      }
+    }
+
+    if (schema.format === 'binary') {
+      return factory.createTypeReferenceNode('Blob', [])
+    }
+
+    // detect assertion "const" and define the type property as a Literal
+    if ('const' in schema && schema['const'] !== undefined && typeof schema['const'] === 'string') {
+      return factory.createLiteralTypeNode(factory.createStringLiteral(schema['const']))
+    }
+
+    return factory.keywordTypeNodes.any
+  }
+}

package/src/generators/index.ts

@@ -0,0 +1,2 @@
+export * from './OperationGenerator.ts'
+export * from './TypeGenerator.ts'

package/src/index.ts

@@ -0,0 +1,6 @@
+import { definePlugin } from './plugin.ts'
+
+export { definePlugin, pluginKey, pluginName } from './plugin.ts'
+export * from './types.ts'
+
+export default definePlugin

package/src/plugin.ts

@@ -0,0 +1,229 @@
+import path from 'node:path'
+
+import { createPlugin, FileManager, PluginManager } from '@kubb/core'
+import { getRelativePath, renderTemplate } from '@kubb/core/utils'
+import { pluginName as swaggerPluginName } from '@kubb/swagger'
+
+import { camelCase, camelCaseTransformMerge, pascalCase, pascalCaseTransformMerge } from 'change-case'
+
+import { TypeBuilder } from './builders/index.ts'
+import { OperationGenerator } from './generators/index.ts'
+
+import type { KubbFile, KubbPlugin } from '@kubb/core'
+import type { OpenAPIV3, PluginOptions as SwaggerPluginOptions } from '@kubb/swagger'
+import type { PluginOptions } from './types.ts'
+
+export const pluginName = 'swagger-ts' satisfies PluginOptions['name']
+export const pluginKey: PluginOptions['key'] = ['schema', pluginName] satisfies PluginOptions['key']
+
+export const definePlugin = createPlugin<PluginOptions>((options) => {
+  const {
+    output = 'types',
+    group,
+    exclude = [],
+    include,
+    override = [],
+    enumType = 'asConst',
+    dateType = 'string',
+    optionalType = 'questionToken',
+    transformers = {},
+    exportAs,
+  } = options
+  const template = group?.output ? group.output : `${output}/{{tag}}Controller`
+  let pluginsOptions: [KubbPlugin<SwaggerPluginOptions>]
+
+  return {
+    name: pluginName,
+    options,
+    kind: 'schema',
+    validate(plugins) {
+      pluginsOptions = PluginManager.getDependedPlugins<SwaggerPluginOptions>(plugins, [swaggerPluginName])
+
+      return true
+    },
+    resolvePath(baseName, directory, options) {
+      const root = path.resolve(this.config.root, this.config.output.path)
+      const mode = FileManager.getMode(path.resolve(root, output))
+
+      if (mode === 'file') {
+        /**
+         * when output is a file then we will always append to the same file(output file), see fileManager.addOrAppend
+         * Other plugins then need to call addOrAppend instead of just add from the fileManager class
+         */
+        return path.resolve(root, output)
+      }
+
+      if (options?.tag && group?.type === 'tag') {
+        const tag = camelCase(options.tag, { delimiter: '', transform: camelCaseTransformMerge })
+
+        return path.resolve(root, renderTemplate(template, { tag }), baseName)
+      }
+
+      return path.resolve(root, output, baseName)
+    },
+    resolveName(name, type) {
+      const resolvedName = pascalCase(name, { delimiter: '', stripRegexp: /[^A-Z0-9$]/gi, transform: pascalCaseTransformMerge })
+
+      if (type) {
+        return transformers?.name?.(resolvedName, type) || resolvedName
+      }
+
+      return resolvedName
+    },
+    async writeFile(source, writePath) {
+      if (!writePath.endsWith('.ts') || !source) {
+        return
+      }
+
+      return this.fileManager.write(source, writePath)
+    },
+    async buildStart() {
+      const [swaggerPlugin] = pluginsOptions
+
+      const oas = await swaggerPlugin.api.getOas()
+
+      const schemas = await swaggerPlugin.api.getSchemas()
+      const root = path.resolve(this.config.root, this.config.output.path)
+      const mode = FileManager.getMode(path.resolve(root, output))
+      // keep the used enumnames between TypeBuilder and OperationGenerator per plugin(pluginKey)
+      const usedEnumNames = {}
+
+      if (mode === 'directory') {
+        const builder = await new TypeBuilder({
+          usedEnumNames,
+          resolveName: (params) => this.resolveName({ pluginKey: this.plugin.key, ...params }),
+          fileResolver: (name) => {
+            const resolvedTypeId = this.resolvePath({
+              baseName: `${name}.ts`,
+              pluginKey: this.plugin.key,
+            })
+
+            const root = this.resolvePath({ baseName: ``, pluginKey: this.plugin.key })
+
+            return getRelativePath(root, resolvedTypeId)
+          },
+          withJSDocs: true,
+          enumType,
+          dateType,
+          optionalType,
+        }).configure()
+        Object.entries(schemas).forEach(([name, schema]: [string, OpenAPIV3.SchemaObject]) => {
+          // generate and pass through new code back to the core so it can be write to that file
+          return builder.add({
+            schema,
+            name,
+          })
+        })
+
+        const mapFolderSchema = async ([name]: [string, OpenAPIV3.SchemaObject]) => {
+          const resolvedPath = this.resolvePath({ baseName: `${this.resolveName({ name, pluginKey: this.plugin.key })}.ts`, pluginKey: this.plugin.key })
+
+          if (!resolvedPath) {
+            return null
+          }
+
+          return this.addFile({
+            path: resolvedPath,
+            baseName: `${this.resolveName({ name, pluginKey: this.plugin.key })}.ts`,
+            source: builder.print(name),
+            meta: {
+              pluginKey: this.plugin.key,
+            },
+          })
+        }
+
+        const promises = Object.entries(schemas).map(mapFolderSchema)
+
+        await Promise.all(promises)
+      }
+
+      if (mode === 'file') {
+        // outside the loop because we need to add files to just one instance to have the correct sorting, see refsSorter
+        const builder = new TypeBuilder({
+          usedEnumNames,
+          resolveName: (params) => this.resolveName({ pluginKey: this.plugin.key, ...params }),
+          withJSDocs: true,
+          enumType,
+          dateType,
+          optionalType,
+        }).configure()
+        Object.entries(schemas).forEach(([name, schema]: [string, OpenAPIV3.SchemaObject]) => {
+          // generate and pass through new code back to the core so it can be write to that file
+          return builder.add({
+            schema,
+            name,
+          })
+        })
+
+        const resolvedPath = this.resolvePath({ baseName: '', pluginKey: this.plugin.key })
+        if (!resolvedPath) {
+          return
+        }
+
+        await this.addFile({
+          path: resolvedPath,
+          baseName: output as KubbFile.BaseName,
+          source: builder.print(),
+          meta: {
+            pluginKey: this.plugin.key,
+          },
+          validate: false,
+        })
+      }
+
+      const operationGenerator = new OperationGenerator(
+        {
+          mode,
+          enumType,
+          dateType,
+          optionalType,
+          usedEnumNames,
+        },
+        {
+          oas,
+          pluginManager: this.pluginManager,
+          plugin: this.plugin,
+          contentType: swaggerPlugin.api.contentType,
+          exclude,
+          include,
+          override,
+        },
+      )
+
+      const files = await operationGenerator.build()
+      await this.addFile(...files)
+    },
+    async buildEnd() {
+      if (this.config.output.write === false) {
+        return
+      }
+
+      const root = path.resolve(this.config.root, this.config.output.path)
+
+      await this.fileManager.addIndexes({
+        root,
+        extName: '.ts',
+        meta: { pluginKey: this.plugin.key },
+        options: {
+          map: (file) => {
+            return {
+              ...file,
+              exports: file.exports?.map((item) => {
+                if (exportAs) {
+                  return {
+                    ...item,
+                    name: exportAs,
+                    asAlias: !!exportAs,
+                  }
+                }
+                return item
+              }),
+            }
+          },
+          output,
+          isTypeOnly: true,
+        },
+      })
+    },
+  }
+})

package/src/types.ts

@@ -0,0 +1,82 @@
+import type { KubbPlugin, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
+import type { Exclude, Include, Override, ResolvePathOptions } from '@kubb/swagger'
+
+export type Options = {
+  /**
+   * Relative path to save the TypeScript types.
+   * When output is a file it will save all models inside that file else it will create a file per schema item.
+   * @default 'types'
+   */
+  output?: string
+  /**
+   * Group the TypeScript types based on the provided name.
+   */
+  group?: {
+    /**
+     * Tag will group based on the operation tag inside the Swagger file.
+     */
+    type: 'tag'
+    /**
+     * Relative path to save the grouped TypeScript Types.
+     *
+     * `{{tag}}` will be replaced by the current tagName.
+     * @example `${output}/{{tag}}Controller` => `models/PetController`
+     * @default `${output}/{{tag}}Controller`
+     */
+    output?: string
+  }
+  /**
+   * Name to be used for the `export * as {{exportAs}} from './`
+   */
+  exportAs?: string
+  /**
+   * Array containing exclude paramaters to exclude/skip tags/operations/methods/paths.
+   */
+  exclude?: Array<Exclude>
+  /**
+   * Array containing include paramaters to include tags/operations/methods/paths.
+   */
+  include?: Array<Include>
+  /**
+   * Array containing override paramaters to override `options` based on tags/operations/methods/paths.
+   */
+  override?: Array<Override<Options>>
+  /**
+   * Choose to use `enum` or `as const` for enums
+   * @default 'asConst'
+   */
+  enumType?: 'enum' | 'asConst' | 'asPascalConst'
+  /**
+   * Choose to use `date` or `datetime` as JavaScript `Date` instead of `string`.
+   * @default 'string'
+   */
+  dateType?: 'string' | 'date'
+  /**
+   * Choose what to use as mode for an optional value.
+   * @examples 'questionToken': type?: string
+   * @examples 'undefined': type: string | undefined
+   * @examples 'questionTokenAndUndefined': type?: string | undefined
+   * @default 'questionToken'
+   */
+  optionalType?: 'questionToken' | 'undefined' | 'questionTokenAndUndefined'
+  transformers?: {
+    /**
+     * Customize the names based on the type that is provided by the plugin.
+     */
+    name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
+  }
+}
+
+export type FileMeta = {
+  pluginKey?: KubbPlugin['key']
+  name?: string
+  tag?: string
+}
+
+export type PluginOptions = PluginFactoryOptions<'swagger-ts', 'schema', Options, Options, never, ResolvePathOptions>
+
+declare module '@kubb/core' {
+  export interface _Register {
+    ['@kubb/swagger-ts']: PluginOptions
+  }
+}