@kubb/swagger-ts 2.0.0-canary.20231030T125204 → 2.0.1

package/src/oas/security.ts

@@ -0,0 +1,158 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/ban-types */
+
+import type { Call, Objects, Tuples } from 'hotscript'
+
+namespace Checks {
+  export type Security = { security: { [key: string]: any }[] }
+
+  export namespace AuthParams {
+    export type Basic =
+      | {
+        type: 'http'
+        scheme: 'basic'
+      }
+      | { type: 'basic' }
+    export type Bearer =
+      | {
+        type: 'http'
+        scheme: 'bearer'
+      }
+      | { type: 'bearer' }
+
+    export type OAuth2 = {
+      type: 'oauth2'
+    }
+    export type ApiKey = {
+      type: 'apiKey'
+      in: 'header'
+    }
+  }
+
+  export namespace AuthName {
+    export type Basic = `basic${string}`
+    export type Bearer = `bearer${string}`
+    export type OAuth2 = `oauth${string}`
+  }
+}
+
+type SecuritySchemeName<T extends Checks.Security> = Call<
+  Tuples.Map<Objects.Keys>,
+  T['security']
+>[number]
+
+namespace AuthParams {
+  export type Basic<TSecurityScheme> = TSecurityScheme extends Checks.AuthParams.Basic ? {
+      headers: {
+        /**
+         * `Authorization` header is required for basic authentication
+         * @see https://en.wikipedia.org/wiki/Basic_access_authentication
+         *
+         * It contains the word `Basic` followed by a space and a base64-encoded string `username:password`
+         *
+         * @example
+         * ```
+         * Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
+         * ```
+         */
+        Authorization: `Basic ${string}`
+      }
+    }
+    : {}
+
+  export type Bearer<TSecurityScheme> = TSecurityScheme extends Checks.AuthParams.Bearer ? {
+      /**
+       * `Authorization` header is required for bearer authentication
+       * @see https://swagger.io/docs/specification/authentication/bearer-authentication/
+       */
+      headers: {
+        /**
+         * It contains the word `Bearer` followed by a space and the token
+         *
+         * @example
+         * ```
+         * Authorization: Bearer {token}
+         * ```
+         */
+        Authorization: `Bearer ${string}`
+      }
+    }
+    : {}
+
+  export type ApiKey<TSecurityScheme> = TSecurityScheme extends Checks.AuthParams.ApiKey & { name: infer TApiKeyHeaderName } ? {
+      headers: {
+        /**
+         * Header required for API key authentication
+         */
+        [THeaderName in TApiKeyHeaderName extends string ? TApiKeyHeaderName : never]: string
+      }
+    }
+    : TSecurityScheme extends {
+      type: 'apiKey'
+      in: 'query'
+      name: infer TApiKeyQueryName
+    } ? {
+        query: {
+          /**
+           * Query parameter required for API key authentication
+           */
+          [TQueryName in TApiKeyQueryName extends string ? TApiKeyQueryName : never]: string
+        }
+      }
+    : {}
+
+  export type OAuth2<TSecurityScheme> = TSecurityScheme extends Checks.AuthParams.OAuth2 ? {
+      /**
+       * `Authorization` header is required for OAuth2.
+       */
+      headers: {
+        /**
+         * The access token string as issued by the authorization server.
+         * @example `Authorization: Bearer <access_token>`
+         */
+        Authorization: `Bearer ${string}`
+      }
+    }
+    : {}
+}
+
+type OASSecurityParams<TSecurityScheme> =
+  & AuthParams.Basic<TSecurityScheme>
+  & AuthParams.Bearer<TSecurityScheme>
+  & AuthParams.ApiKey<TSecurityScheme>
+  & AuthParams.OAuth2<TSecurityScheme>
+
+export type SecurityParamsBySecurityRef<TOAS, TSecurityObj> = TSecurityObj extends Checks.Security ? TOAS extends
+    | {
+      components: {
+        securitySchemes: {
+          [
+            TSecuritySchemeNameKey in SecuritySchemeName<TSecurityObj> extends string ? SecuritySchemeName<TSecurityObj>
+              : never
+          ]: infer TSecurityScheme
+        }
+      }
+    }
+    | {
+      securityDefinitions: {
+        [
+          TSecuritySchemeNameKey in SecuritySchemeName<TSecurityObj> extends string ? SecuritySchemeName<TSecurityObj>
+            : never
+        ]: infer TSecurityScheme
+      }
+    } ? OASSecurityParams<TSecurityScheme>
+    // OAS may have a bad reference to a security scheme
+    // So we can assume it
+  : SecuritySchemeName<TSecurityObj> extends Checks.AuthName.Basic ? AuthParams.Basic<{
+      type: 'http'
+      scheme: 'basic'
+    }>
+  : SecuritySchemeName<TSecurityObj> extends Checks.AuthName.Bearer ? AuthParams.Bearer<{
+      type: 'http'
+      scheme: 'bearer'
+    }>
+  : SecuritySchemeName<TSecurityObj> extends Checks.AuthName.OAuth2 ? AuthParams.OAuth2<{
+      type: 'oauth2'
+    }>
+  : {}
+  : {}

package/src/plugin.ts

@@ -0,0 +1,174 @@
+import path from 'node:path'
+
+import { createPlugin, FileManager, PluginManager } from '@kubb/core'
+import { camelCase, pascalCase } from '@kubb/core/transformers'
+import { renderTemplate } from '@kubb/core/utils'
+import { pluginName as swaggerPluginName } from '@kubb/swagger'
+
+import { OperationGenerator } from './OperationGenerator.tsx'
+import { TypeBuilder } from './TypeBuilder.ts'
+
+import type { KubbFile, KubbPlugin } from '@kubb/core'
+import type { PluginOptions as SwaggerPluginOptions } from '@kubb/swagger'
+import type { OasTypes } from '@kubb/swagger/oas'
+import type { PluginOptions } from './types.ts'
+export const pluginName = 'swagger-ts' satisfies PluginOptions['name']
+export const pluginKey: PluginOptions['key'] = [pluginName] satisfies PluginOptions['key']
+
+export const definePlugin = createPlugin<PluginOptions>((options) => {
+  const {
+    output = { path: 'types' },
+    group,
+    exclude = [],
+    include,
+    override = [],
+    enumType = 'asConst',
+    dateType = 'string',
+    optionalType = 'questionToken',
+    transformers = {},
+    oasType = false,
+  } = options
+  const template = group?.output ? group.output : `${output.path}/{{tag}}Controller`
+
+  return {
+    name: pluginName,
+    options: {
+      transformers,
+      dateType,
+      enumType,
+      optionalType,
+      oasType,
+      // keep the used enumnames between TypeBuilder and OperationGenerator per plugin(pluginKey)
+      usedEnumNames: {},
+    },
+    pre: [swaggerPluginName],
+    resolvePath(baseName, directory, options) {
+      const root = path.resolve(this.config.root, this.config.output.path)
+      const mode = FileManager.getMode(path.resolve(root, output.path))
+
+      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.path)
+      }
+
+      if (options?.tag && group?.type === 'tag') {
+        const tag = camelCase(options.tag)
+
+        return path.resolve(root, renderTemplate(template, { tag }), baseName)
+      }
+
+      return path.resolve(root, output.path, baseName)
+    },
+    resolveName(name, type) {
+      const resolvedName = pascalCase(name)
+
+      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, { sanity: false })
+    },
+    async buildStart() {
+      const [swaggerPlugin]: [KubbPlugin<SwaggerPluginOptions>] = PluginManager.getDependedPlugins<SwaggerPluginOptions>(this.plugins, [swaggerPluginName])
+
+      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.path))
+      const builder = new TypeBuilder(this.plugin.options, { oas, pluginManager: this.pluginManager })
+
+      builder.add(
+        Object.entries(schemas).map(([name, schema]: [string, OasTypes.SchemaObject]) => ({ name, schema })),
+      )
+
+      if (mode === 'directory') {
+        const mapFolderSchema = async ([name]: [string, OasTypes.SchemaObject]) => {
+          const baseName = `${this.resolveName({ name, pluginKey: this.plugin.key, type: 'file' })}.ts` as const
+          const resolvedPath = this.resolvePath({ baseName, pluginKey: this.plugin.key })
+          const { source, imports } = builder.build(name)
+
+          if (!resolvedPath) {
+            return null
+          }
+
+          return this.addFile({
+            path: resolvedPath,
+            baseName,
+            source,
+            imports: imports.map(item => ({ ...item, root: resolvedPath })),
+            meta: {
+              pluginKey: this.plugin.key,
+            },
+          })
+        }
+
+        const promises = Object.entries(schemas).map(mapFolderSchema)
+
+        await Promise.all(promises)
+      }
+
+      if (mode === 'file') {
+        const resolvedPath = this.resolvePath({ baseName: '', pluginKey: this.plugin.key })
+        const { source } = builder.build()
+
+        if (!resolvedPath) {
+          return
+        }
+
+        await this.addFile({
+          path: resolvedPath,
+          baseName: output.path as KubbFile.BaseName,
+          source,
+          imports: [],
+          meta: {
+            pluginKey: this.plugin.key,
+          },
+        })
+      }
+
+      const operationGenerator = new OperationGenerator(
+        this.plugin.options,
+        {
+          oas,
+          pluginManager: this.pluginManager,
+          plugin: this.plugin,
+          contentType: swaggerPlugin.api.contentType,
+          exclude,
+          include,
+          override,
+          mode,
+        },
+      )
+
+      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)
+      const { exportType = 'barrel' } = output
+
+      if (exportType === 'barrel') {
+        await this.fileManager.addIndexes({
+          root,
+          output,
+          meta: { pluginKey: this.plugin.key },
+        })
+      }
+    },
+  }
+})

package/src/types.ts

@@ -0,0 +1,110 @@
+import type { KubbFile, KubbPlugin, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
+import type { AppMeta as SwaggerAppMeta, Exclude, Include, Override, ResolvePathOptions } from '@kubb/swagger'
+
+export type Options = {
+  output?: {
+    /**
+     * 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'
+     */
+    path: string
+    /**
+     * Name to be used for the `export * as {{exportAs}} from './'`
+     */
+    exportAs?: string
+    /**
+     * Add an extension to the generated imports and exports, default it will not use an extension
+     */
+    extName?: KubbFile.Extname
+    /**
+     * Define what needs to exported, here you can also disable the export of barrel files
+     * @default `'barrel'`
+     */
+    exportType?: 'barrel' | false
+  }
+  /**
+   * 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
+  }
+  /**
+   * 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 an Oas object as Oas type with `import type { Infer } from '@kubb/swagger-ts/oas'`
+   */
+  oasType?: 'infer' | false
+}
+
+type ResolvedOptions = {
+  enumType: NonNullable<Options['enumType']>
+  dateType: NonNullable<Options['dateType']>
+  optionalType: NonNullable<Options['optionalType']>
+  transformers: NonNullable<Options['transformers']>
+  oasType: NonNullable<Options['oasType']>
+  usedEnumNames: Record<string, number>
+}
+
+export type FileMeta = {
+  pluginKey?: KubbPlugin['key']
+  name?: string
+  tag?: string
+}
+
+type AppMeta = SwaggerAppMeta
+
+export type PluginOptions = PluginFactoryOptions<'swagger-ts', Options, ResolvedOptions, never, ResolvePathOptions, AppMeta>
+
+declare module '@kubb/core' {
+  export interface _Register {
+    ['@kubb/swagger-ts']: PluginOptions
+  }
+}
+// external packages
+export * as Oas from './oas/index.ts'