@kubb/plugin-oas 0.0.0-canary-20240509211223

package/src/plugin.ts

@@ -0,0 +1,133 @@
+import path from 'node:path'
+
+import { createPlugin } from '@kubb/core'
+import { camelCase } from '@kubb/core/transformers'
+
+import { getSchemas } from './utils/getSchemas.ts'
+
+import type { Config } from '@kubb/core'
+import type { Logger } from '@kubb/core/logger'
+import type { Oas, OasTypes } from '@kubb/oas'
+import type { FormatOptions } from '@kubb/oas/parser'
+import type { PluginOas } from './types.ts'
+import { parseFromConfig } from './utils/parseFromConfig.ts'
+
+export const pluginOasName = 'plugin-oas' satisfies PluginOas['name']
+
+export const pluginOas = createPlugin<PluginOas>((options) => {
+  const {
+    output = { path: 'schemas', export: false },
+    experimentalFilter: filter,
+    experimentalSort: sort,
+    validate = true,
+    serverIndex = 0,
+    contentType,
+  } = options
+
+  const getOas = async ({ config, logger, formatOptions }: { config: Config; logger: Logger; formatOptions?: FormatOptions }): Promise<Oas> => {
+    try {
+      // needs to be in a different variable or the catch here will not work(return of a promise instead)
+      const oas = await parseFromConfig(config, formatOptions)
+
+      if (validate) {
+        await oas.valdiate()
+      }
+
+      return oas
+    } catch (e) {
+      const error = e as Error
+
+      logger.emit('warning', error?.message)
+      return parseFromConfig(config)
+    }
+  }
+
+  return {
+    name: pluginOasName,
+    options,
+
+    api() {
+      const { config, logger } = this
+
+      return {
+        getOas(formatOptions) {
+          return getOas({ config, logger, formatOptions })
+        },
+        async getSchemas({ includes } = {}) {
+          const oas = await this.getOas()
+          return getSchemas({ oas, contentType, includes })
+        },
+        async getBaseURL() {
+          const oasInstance = await this.getOas()
+          const baseURL = oasInstance.api.servers?.at(serverIndex)?.url
+          return baseURL
+        },
+        contentType,
+      }
+    },
+    resolvePath(baseName) {
+      if (output === false) {
+        return undefined
+      }
+
+      const root = path.resolve(this.config.root, this.config.output.path)
+
+      return path.resolve(root, output.path, baseName)
+    },
+    resolveName(name, type) {
+      return camelCase(name, { isFile: type === 'file' })
+    },
+    async writeFile(source, writePath) {
+      if (!writePath.endsWith('.json') || !source) {
+        return
+      }
+
+      return this.fileManager.write(source, writePath, { sanity: false })
+    },
+    async buildStart() {
+      if (!output) {
+        return
+      }
+
+      const oas = await getOas({
+        config: this.config,
+        logger: this.logger,
+        formatOptions: {
+          filterSet: filter,
+          sortSet: sort,
+        },
+      })
+      await oas.dereference()
+      const schemas = getSchemas({ oas, contentType })
+
+      const mapSchema = async ([name, schema]: [string, OasTypes.SchemaObject]) => {
+        const resolvedPath = this.resolvePath({
+          baseName: `${name}.json`,
+          pluginKey: this.plugin.key,
+        })
+
+        const resvoledFileName = this.resolveName({
+          name: `${name}.json`,
+          pluginKey: [pluginOasName],
+          type: 'file',
+        }) as `${string}.json`
+
+        if (!resolvedPath) {
+          return
+        }
+
+        await this.addFile({
+          path: resolvedPath,
+          baseName: resvoledFileName,
+          source: JSON.stringify(schema),
+          meta: {
+            pluginKey: this.plugin.key,
+          },
+        })
+      }
+
+      const promises = Object.entries(schemas).map(mapSchema)
+      await Promise.all(promises)
+    },
+  }
+})

package/src/types.ts

@@ -0,0 +1,147 @@
+import type { Plugin } from '@kubb/core'
+import type { KubbFile, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
+import type { HttpMethod, Oas, Operation, SchemaObject, contentType } from '@kubb/oas'
+import type { FormatOptions } from '@kubb/oas/parser'
+import type { GetSchemasProps } from './utils/getSchemas.ts'
+
+export type ResolvePathOptions = {
+  pluginKey?: Plugin['key']
+  tag?: string
+  type?: ResolveNameParams['type']
+}
+
+export type API = {
+  getOas: (formatOptions?: FormatOptions) => Promise<Oas>
+  getSchemas: (options?: Pick<GetSchemasProps, 'includes'>) => Promise<Record<string, SchemaObject>>
+  getBaseURL: () => Promise<string | undefined>
+  contentType?: contentType
+}
+
+export type Options = {
+  /**
+   * Validate your input(see kubb.config) based on '@apidevtools/swagger-parser'.
+   * @default true
+   */
+  validate?: boolean
+  output?:
+    | {
+        /**
+         * Relative path to save the JSON models.
+         * False will not generate the schema JSON's.
+         * @default 'schemas'
+         */
+        path: string
+      }
+    | false
+  /**
+   * Which server to use from the array of `servers.url[serverIndex]`
+   * @example
+   * - `0` will return `http://petstore.swagger.io/api`
+   * - `1` will return `http://localhost:3000`
+   * @default 0
+   */
+  serverIndex?: number
+  /**
+   * Define which contentType should be used.
+   * By default, this is set based on the first used contentType..
+   */
+  contentType?: contentType
+  experimentalFilter?: FormatOptions['filterSet']
+  experimentalSort?: FormatOptions['sortSet']
+}
+
+/**
+ * `propertyName` is the ref name + resolved with the nameResolver
+ *  @example `import { Pet } from './Pet'`
+ *
+ * `originalName` is the original name used(in PascalCase), only used to remove duplicates
+ *
+ * `pluginKey` can be used to override the current plugin being used, handy when you want to import a type/schema out of another plugin
+ * @example import a type(swagger-ts) for a mock file(swagger-faker)
+ */
+
+export type Ref = {
+  propertyName: string
+  originalName: string
+  path: KubbFile.OptionalPath
+  pluginKey?: Plugin['key']
+}
+export type Refs = Record<string, Ref>
+
+export type Resolver = {
+  /**
+   * Original name or name resolved by `resolveName({ name: operation?.getOperationId() as string, pluginName })`
+   */
+  name: string
+  baseName: KubbFile.BaseName
+  path: KubbFile.Path
+}
+
+export type OperationSchema = {
+  /**
+   * Converted name, contains already `PathParams`, `QueryParams`, ...
+   */
+  name: string
+  schema: SchemaObject
+  operation?: Operation
+  /**
+   * OperationName in PascalCase, only being used in OperationGenerator
+   */
+  operationName?: string
+  description?: string
+  statusCode?: number
+  keys?: string[]
+  keysToOmit?: string[]
+  withData?: boolean
+}
+
+export type OperationSchemas = {
+  pathParams?: OperationSchema & { keysToOmit?: never }
+  queryParams?: OperationSchema & { keysToOmit?: never }
+  headerParams?: OperationSchema & { keysToOmit?: never }
+  request?: OperationSchema
+  response: OperationSchema
+  statusCodes?: Array<OperationSchema>
+  errors?: Array<OperationSchema>
+}
+
+export type OperationsByMethod = Record<string, Record<HttpMethod, { operation: Operation; schemas: OperationSchemas }>>
+type ByTag = {
+  type: 'tag'
+  pattern: string | RegExp
+}
+
+type ByOperationId = {
+  type: 'operationId'
+  pattern: string | RegExp
+}
+
+type ByPath = {
+  type: 'path'
+  pattern: string | RegExp
+}
+
+type ByMethod = {
+  type: 'method'
+  pattern: HttpMethod | RegExp
+}
+
+type BySchemaName = {
+  type: 'schemaName'
+  pattern: string | RegExp
+}
+
+export type Exclude = ByTag | ByOperationId | ByPath | ByMethod
+export type Include = ByTag | ByOperationId | ByPath | ByMethod
+
+export type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName) & {
+  options: Partial<TOptions>
+}
+
+export type PluginOas = PluginFactoryOptions<'plugin-oas', Options, Options, API, never>
+
+declare module '@kubb/core' {
+  export interface _Register {
+    ['@kubb/plugin-oas']: PluginOas
+  }
+}

package/src/utils/getComments.ts

@@ -0,0 +1,15 @@
+import transformers from '@kubb/core/transformers'
+import { URLPath } from '@kubb/core/utils'
+
+import type { Operation } from '@kubb/oas'
+
+export function getComments(operation: Operation): string[] {
+  return [
+    operation.getDescription() && `@description ${operation.getDescription()}`,
+    operation.getSummary() && `@summary ${operation.getSummary()}`,
+    operation.path && `@link ${new URLPath(operation.path).URL}`,
+    operation.isDeprecated() && '@deprecated',
+  ]
+    .filter(Boolean)
+    .map((text) => transformers.trim(text))
+}

package/src/utils/getGroupedByTagFiles.ts

@@ -0,0 +1,81 @@
+import { resolve } from 'node:path'
+
+import { FileManager } from '@kubb/core'
+import { getRelativePath } from '@kubb/core/fs'
+import transformers from '@kubb/core/transformers'
+import { renderTemplate } from '@kubb/core/utils'
+
+import type { KubbFile, Plugin } from '@kubb/core'
+import type { Logger } from '@kubb/core/logger'
+
+type Options = {
+  logger: Logger
+  files: KubbFile.File[]
+  plugin: Plugin
+  template: string
+  exportAs: string
+  /**
+   * Root based on root and output.path specified in the config
+   */
+  root: string
+  /**
+   * Output for plugin
+   */
+  output: {
+    path: string
+    exportAs?: string
+    extName?: KubbFile.Extname
+    exportType?: 'barrel' | 'barrelNamed' | false
+  }
+}
+
+type FileMeta = {
+  pluginKey?: Plugin['key']
+  tag?: string
+}
+
+export async function getGroupedByTagFiles({ logger, files, plugin, template, exportAs, root, output }: Options): Promise<KubbFile.File<FileMeta>[]> {
+  const { path, exportType = 'barrel' } = output
+  const mode = FileManager.getMode(resolve(root, path))
+
+  if (mode === 'single' || exportType === false) {
+    return []
+  }
+
+  return files
+    .filter((file) => {
+      const name = file.meta?.pluginKey?.[0]
+      return name === plugin.name
+    })
+    .map((file: KubbFile.File<FileMeta>) => {
+      if (!file.meta?.tag) {
+        logger?.emit('debug', [`Could not find a tagName for ${JSON.stringify(file, undefined, 2)}`])
+
+        return
+      }
+
+      const tag = file.meta?.tag && transformers.camelCase(file.meta.tag)
+      const tagPath = getRelativePath(resolve(root, output.path), resolve(root, renderTemplate(template, { tag })))
+      const tagName = renderTemplate(exportAs, { tag })
+
+      if (tagName) {
+        return {
+          baseName: 'index.ts' as const,
+          path: resolve(root, output.path, 'index.ts'),
+          source: '',
+          exports: [
+            {
+              path: output.extName ? `${tagPath}/index${output.extName}` : `${tagPath}/index`,
+              asAlias: true,
+              name: tagName,
+            },
+          ],
+          meta: {
+            pluginKey: plugin.key,
+          },
+          exportable: true,
+        }
+      }
+    })
+    .filter(Boolean)
+}

package/src/utils/getParams.ts

@@ -0,0 +1,57 @@
+import { isParameterObject } from '@kubb/oas'
+
+import type { FunctionParamsAST } from '@kubb/core/utils'
+import type { OasTypes } from '@kubb/oas'
+import type { Params } from '@kubb/react'
+import type { OperationSchema } from '../types.ts'
+/**
+ *
+ * @deprecated
+ * TODO move to operationManager hook
+ */
+export function getASTParams(
+  operationSchema: OperationSchema | undefined,
+  {
+    typed = false,
+    override,
+  }: {
+    typed?: boolean
+    override?: (data: FunctionParamsAST) => FunctionParamsAST
+  } = {},
+): FunctionParamsAST[] {
+  if (!operationSchema || !operationSchema.schema.properties || !operationSchema.name) {
+    return []
+  }
+
+  return Object.entries(operationSchema.schema.properties).map(([name, schema]: [string, OasTypes.SchemaObject]) => {
+    const isParam = isParameterObject(schema)
+    const data: FunctionParamsAST = {
+      name,
+      enabled: !!name,
+      required: isParam ? schema.required : true,
+      type: typed ? `${operationSchema.name}["${name}"]` : undefined,
+    }
+
+    return override ? override(data) : data
+  })
+}
+
+export function getPathParams(
+  operationSchema: OperationSchema | undefined,
+  options: {
+    typed?: boolean
+    override?: (data: FunctionParamsAST) => FunctionParamsAST
+  } = {},
+) {
+  return getASTParams(operationSchema, options).reduce((acc, curr) => {
+    if (curr.name && curr.enabled) {
+      acc[curr.name] = {
+        default: curr.default,
+        type: curr.type,
+        optional: !curr.required,
+      }
+    }
+
+    return acc
+  }, {} as Params)
+}

package/src/utils/getSchemaFactory.ts

@@ -0,0 +1,33 @@
+import { isOpenApiV3_1Document } from '@kubb/oas'
+
+import type { Oas, OpenAPIV3, OpenAPIV3_1, SchemaObject } from '@kubb/oas'
+
+/**
+ * Make it possible to narrow down the schema based on a specific version(3 or 3.1)
+ */
+type SchemaResult<TWithRef extends boolean = false> =
+  | {
+      schema?: (TWithRef extends true ? OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject : OpenAPIV3.SchemaObject) & {
+        nullable?: boolean
+        'x-nullable'?: boolean
+      }
+      version: '3.0'
+    }
+  | {
+      schema?: (TWithRef extends true ? OpenAPIV3_1.SchemaObject | OpenAPIV3_1.ReferenceObject : OpenAPIV3_1.SchemaObject) & {
+        nullable?: boolean
+        'x-nullable'?: boolean
+      }
+      version: '3.1'
+    }
+
+export function getSchemaFactory<TWithRef extends boolean = false>(oas: Oas): (schema?: SchemaObject) => SchemaResult<TWithRef> {
+  return (schema?: SchemaObject) => {
+    const version = isOpenApiV3_1Document(oas.api) ? '3.1' : '3.0'
+
+    return {
+      schema,
+      version,
+    } as SchemaResult<TWithRef>
+  }
+}

package/src/utils/getSchemas.ts

@@ -0,0 +1,45 @@
+import type { Oas, OasTypes, contentType } from '@kubb/oas'
+
+type Mode = 'schemas' | 'responses' | 'requestBodies'
+
+export type GetSchemasProps = {
+  oas: Oas
+  contentType?: contentType
+  includes?: Mode[]
+}
+
+export function getSchemas({ oas, contentType, includes = ['schemas', 'requestBodies', 'responses'] }: GetSchemasProps): Record<string, OasTypes.SchemaObject> {
+  const components = oas.getDefinition().components
+
+  let schemas: Record<string, OasTypes.SchemaObject> = {}
+
+  if (includes.includes('schemas')) {
+    schemas = {
+      ...schemas,
+      ...((components?.schemas as Record<string, OasTypes.SchemaObject>) || {}),
+    }
+  }
+
+  const requestBodies = components?.requestBodies || {}
+  if (includes.includes('responses')) {
+    const responses = components?.responses || {}
+
+    Object.entries(responses).forEach(([name, response]: [string, OasTypes.ResponseObject]) => {
+      if (response.content && !schemas[name]) {
+        const firstContentType = Object.keys(response.content)[0] || 'application/json'
+        schemas[name] = response.content?.[contentType || firstContentType]?.schema as OasTypes.SchemaObject
+      }
+    })
+  }
+
+  if (includes.includes('requestBodies')) {
+    Object.entries(requestBodies).forEach(([name, request]: [string, OasTypes.RequestBodyObject]) => {
+      if (request.content && !schemas[name]) {
+        const firstContentType = Object.keys(request.content)[0] || 'application/json'
+        schemas[name] = request.content?.[contentType || firstContentType]?.schema as OasTypes.SchemaObject
+      }
+    })
+  }
+
+  return schemas
+}

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+export { getComments } from './getComments.ts'
+export { getGroupedByTagFiles } from './getGroupedByTagFiles.ts'
+export { getASTParams, getPathParams } from './getParams.ts'
+export { getSchemaFactory } from './getSchemaFactory.ts'
+export type { GetSchemasProps } from './getSchemas.ts'
+export { getSchemas } from './getSchemas.ts'
+export { refsSorter } from './refSorter.ts'
+export { parseFromConfig } from './parseFromConfig.ts'

package/src/utils/parseFromConfig.ts

@@ -0,0 +1,36 @@
+import { resolve } from 'node:path'
+
+import { URLPath } from '@kubb/core/utils'
+
+import { type FormatOptions, parse } from '@kubb/oas/parser'
+
+import type { Config } from '@kubb/core'
+import type { Oas, OasTypes } from '@kubb/oas'
+import yaml from '@stoplight/yaml'
+
+export function parseFromConfig(config: Config, options: FormatOptions = {}): Promise<Oas> {
+  if ('data' in config.input) {
+    if (typeof config.input.data === 'object') {
+      const api: OasTypes.OASDocument = JSON.parse(JSON.stringify(config.input.data)) as OasTypes.OASDocument
+      return parse(api, options)
+    }
+
+    try {
+      const api: string = yaml.parse(config.input.data as string) as string
+
+      return parse(api, options)
+    } catch (e) {
+      /* empty */
+    }
+
+    const api: OasTypes.OASDocument = JSON.parse(JSON.stringify(config.input.data)) as OasTypes.OASDocument
+
+    return parse(api, options)
+  }
+
+  if (new URLPath(config.input.path).isURL) {
+    return parse(config.input.path, options)
+  }
+
+  return parse(resolve(config.root, config.input.path), options)
+}

package/src/utils/refSorter.ts

@@ -0,0 +1,13 @@
+import type { Refs } from '../types.ts'
+
+type Generated = { import: { refs: Refs; name: string } }
+
+export function refsSorter<T extends Generated>(a: T, b: T): number {
+  if (Object.keys(a.import.refs)?.length < Object.keys(b.import.refs)?.length) {
+    return -1
+  }
+  if (Object.keys(a.import.refs)?.length > Object.keys(b.import.refs)?.length) {
+    return 1
+  }
+  return 0
+}