@kubb/ast 5.0.0-alpha.3 → 5.0.0-alpha.31

package/src/index.ts

@@ -1,7 +1,25 @@
-export { httpMethods, mediaTypes, nodeKinds, schemaTypes } from './constants.ts'
-export { createOperation, createParameter, createProperty, createResponse, createRoot, createSchema } from './factory.ts'
-export { isOperationNode, isParameterNode, isPropertyNode, isResponseNode, isRootNode, isSchemaNode, narrowSchema } from './guards.ts'
-export { definePrinter } from './printer.ts'
-export { buildRefMap, refMapToObject, resolveRef } from './refs.ts'
-export { isPlainStringType } from './utils.ts'
-export { collect, transform, walk } from './visitor.ts'
+export type { ScalarPrimitive } from './constants.ts'
+export { httpMethods, isScalarPrimitive, mediaTypes, schemaTypes } from './constants.ts'
+export {
+  createFunctionParameter,
+  createFunctionParameters,
+  createOperation,
+  createParameter,
+  createParameterGroup,
+  createProperty,
+  createResponse,
+  createRoot,
+  createSchema,
+  createTypeNode,
+  syncOptionality,
+} from './factory.ts'
+export { isOperationNode, isSchemaNode, narrowSchema } from './guards.ts'
+export type { ParserOptions } from './infer.ts'
+export type { Printer, PrinterFactoryOptions, PrinterPartial } from './printer.ts'
+export { createPrinterFactory, definePrinter } from './printer.ts'
+export { extractRefName } from './refs.ts'
+export { childName, collectImports, enumPropName, findDiscriminator } from './resolvers.ts'
+export { mergeAdjacentObjects, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
+export type { OperationParamsResolver } from './utils.ts'
+export { caseParams, createDiscriminantNode, createOperationParams, isStringType, syncSchemaRef } from './utils.ts'
+export { collect, composeTransformers, transform, walk } from './visitor.ts'

package/src/infer.ts

@@ -0,0 +1,130 @@
+import type {
+  ArraySchemaNode,
+  DateSchemaNode,
+  DatetimeSchemaNode,
+  EnumSchemaNode,
+  IntersectionSchemaNode,
+  NumberSchemaNode,
+  ObjectSchemaNode,
+  RefSchemaNode,
+  ScalarSchemaNode,
+  SchemaNode,
+  StringSchemaNode,
+  TimeSchemaNode,
+  UnionSchemaNode,
+  UrlSchemaNode,
+} from './nodes/index.ts'
+
+/**
+ * Shared parser options used by OAS-to-AST inference and parser flows.
+ */
+export type ParserOptions = {
+  /**
+   * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
+   */
+  dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
+  /**
+   * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
+   */
+  integerType?: 'number' | 'bigint'
+  /**
+   * AST type used when no schema type can be inferred.
+   */
+  unknownType: 'any' | 'unknown' | 'void'
+  /**
+   * AST type used for completely empty schemas (`{}`).
+   */
+  emptySchemaType: 'any' | 'unknown' | 'void'
+  /**
+   * Suffix appended to derived enum names when building property schema names.
+   */
+  enumSuffix: 'enum' | (string & {})
+}
+
+/**
+ * Maps each `dateType` option value to the AST node produced by `format: 'date-time'`.
+ */
+type DateTimeNodeByDateType = {
+  date: DateSchemaNode
+  string: DatetimeSchemaNode
+  stringOffset: DatetimeSchemaNode
+  stringLocal: DatetimeSchemaNode
+  false: StringSchemaNode
+}
+
+/**
+ * Resolves the AST node produced by `format: 'date-time'` based on the `dateType` option.
+ */
+type ResolveDateTimeNode<TDateType extends ParserOptions['dateType']> = DateTimeNodeByDateType[TDateType extends keyof DateTimeNodeByDateType
+  ? TDateType
+  : 'string']
+
+/**
+ * Ordered list of `[schema-shape, SchemaNode]` pairs.
+ * `InferSchemaNode` walks this tuple in order and returns the first matching node type.
+ */
+type SchemaNodeMap<TDateType extends ParserOptions['dateType'] = 'string'> = [
+  [{ $ref: string }, RefSchemaNode],
+  [{ allOf: ReadonlyArray<unknown>; properties: object }, IntersectionSchemaNode],
+  [{ allOf: readonly [unknown, unknown, ...unknown[]] }, IntersectionSchemaNode],
+  [{ allOf: ReadonlyArray<unknown> }, SchemaNode],
+  [{ oneOf: ReadonlyArray<unknown> }, UnionSchemaNode],
+  [{ anyOf: ReadonlyArray<unknown> }, UnionSchemaNode],
+  [{ const: null }, ScalarSchemaNode],
+  [{ const: string | number | boolean }, EnumSchemaNode],
+  [{ type: ReadonlyArray<string> }, UnionSchemaNode],
+  [{ type: 'array'; enum: ReadonlyArray<unknown> }, ArraySchemaNode],
+  [{ enum: ReadonlyArray<unknown> }, EnumSchemaNode],
+  [{ type: 'enum' }, EnumSchemaNode],
+  [{ type: 'union' }, UnionSchemaNode],
+  [{ type: 'intersection' }, IntersectionSchemaNode],
+  [{ type: 'tuple' }, ArraySchemaNode],
+  [{ type: 'ref' }, RefSchemaNode],
+  [{ type: 'datetime' }, DatetimeSchemaNode],
+  [{ type: 'date' }, DateSchemaNode],
+  [{ type: 'time' }, TimeSchemaNode],
+  [{ type: 'url' }, UrlSchemaNode],
+  [{ type: 'object' }, ObjectSchemaNode],
+  [{ additionalProperties: boolean | {} }, ObjectSchemaNode],
+  [{ type: 'array' }, ArraySchemaNode],
+  [{ items: object }, ArraySchemaNode],
+  [{ prefixItems: ReadonlyArray<unknown> }, ArraySchemaNode],
+  [{ type: string; format: 'date-time' }, ResolveDateTimeNode<TDateType>],
+  [{ type: string; format: 'date' }, DateSchemaNode],
+  [{ type: string; format: 'time' }, TimeSchemaNode],
+  [{ format: 'date-time' }, ResolveDateTimeNode<TDateType>],
+  [{ format: 'date' }, DateSchemaNode],
+  [{ format: 'time' }, TimeSchemaNode],
+  [{ type: 'string' }, StringSchemaNode],
+  [{ type: 'number' }, NumberSchemaNode],
+  [{ type: 'integer' }, NumberSchemaNode],
+  [{ type: 'bigint' }, NumberSchemaNode],
+  [{ type: string }, ScalarSchemaNode],
+  [{ minLength: number }, StringSchemaNode],
+  [{ maxLength: number }, StringSchemaNode],
+  [{ pattern: string }, StringSchemaNode],
+  [{ minimum: number }, NumberSchemaNode],
+  [{ maximum: number }, NumberSchemaNode],
+]
+
+/**
+ * Infers the matching AST `SchemaNode` type from an input schema shape.
+ */
+export type InferSchemaNode<
+  TSchema extends object,
+  TDateType extends ParserOptions['dateType'] = 'string',
+  TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
+> = TEntries extends [infer TEntry extends [object, SchemaNode], ...infer TRest extends ReadonlyArray<[object, SchemaNode]>]
+  ? TSchema extends TEntry[0]
+    ? TEntry[1]
+    : InferSchemaNode<TSchema, TDateType, TRest>
+  : SchemaNode
+
+/**
+ * Backward-compatible alias for `InferSchemaNode`.
+ */
+export type InferSchema<
+  TSchema extends object,
+  TDateType extends ParserOptions['dateType'] = 'string',
+  TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
+> = InferSchemaNode<TSchema, TDateType, TEntries>

package/src/mocks.ts

@@ -2,7 +2,7 @@ import { createOperation, createParameter, createProperty, createResponse, creat
 import type { RootNode } from './nodes/root.ts'
 
 /**
- * Minimal single-resource tree: one `Pet` schema and one `getPetById` operation.
+ * Builds a minimal sample AST with one `Pet` schema and one `getPetById` operation.
  */
 export function buildSampleTree(): RootNode {
   const petSchema = createSchema({
@@ -20,15 +20,22 @@ export function buildSampleTree(): RootNode {
     path: '/pets/{petId}',
     tags: ['pets'],
     parameters: [createParameter({ name: 'petId', in: 'path', schema: createSchema({ type: 'integer' }), required: true })],
-    responses: [createResponse({ statusCode: '200', schema: createSchema({ type: 'ref', name: 'Pet' }) }), createResponse({ statusCode: '404' })],
+    responses: [
+      createResponse({ statusCode: '200', schema: createSchema({ type: 'ref', name: 'Pet' }) }),
+      createResponse({
+        statusCode: '404',
+        schema: createSchema({ type: 'ref', name: 'Error' }),
+      }),
+    ],
   })
 
   return createRoot({ schemas: [petSchema], operations: [operation] })
 }
 
 /**
- * PetStore-like tree: six named schemas (`Pet`, `NewPet`, `PetList`, `Error`, `PetOrError`, `FullPet`)
- * and two operations (`listPets`, `createPet`).
+ * Builds a PetStore-like fixture AST with:
+ * - six named schemas (`Pet`, `NewPet`, `PetList`, `Error`, `PetOrError`, `FullPet`)
+ * - two operations (`listPets`, `createPet`)
  */
 export function buildFixture(): RootNode {
   const refPet = createSchema({ type: 'ref', ref: 'Pet' })
@@ -92,7 +99,7 @@ export function buildFixture(): RootNode {
         method: 'POST',
         path: '/pets',
         tags: ['pets'],
-        requestBody: createSchema({ type: 'ref', ref: 'NewPet' }),
+        requestBody: { schema: createSchema({ type: 'ref', ref: 'NewPet' }) },
         responses: [createResponse({ statusCode: '201', schema: refPet, mediaType: 'application/json' })],
       }),
     ],

package/src/nodes/base.ts

@@ -1,16 +1,44 @@
 /**
- * Kind discriminant for every AST node.
+ * `kind` values used by AST nodes.
+ *
+ * @example
+ * ```ts
+ * const kind: NodeKind = 'Schema'
+ * ```
  */
-export type NodeKind = 'Root' | 'Operation' | 'Schema' | 'Property' | 'Parameter' | 'Response'
+export type NodeKind =
+  | 'Root'
+  | 'Operation'
+  | 'Schema'
+  | 'Property'
+  | 'Parameter'
+  | 'Response'
+  | 'FunctionParameter'
+  | 'ParameterGroup'
+  | 'FunctionParameters'
+  | 'Type'
 
 /**
- * Common base for all AST nodes.
+ * Base shape shared by all AST nodes.
+ *
+ * @example
+ * ```ts
+ * const base: BaseNode = { kind: 'Root' }
+ * ```
  */
 export type BaseNode = {
+  /**
+   * Node discriminator.
+   */
   kind: NodeKind
 }
 
 /**
- * Any AST node.
+ * Minimal node type when only `kind` is needed.
+ *
+ * @example
+ * ```ts
+ * const node: Node = { kind: 'Operation' }
+ * ```
  */
 export type Node = BaseNode

package/src/nodes/function.ts

@@ -0,0 +1,201 @@
+import type { BaseNode } from './base.ts'
+
+/**
+ * AST node representing a language-agnostic type expression produced during parameter resolution.
+ * Each language printer renders the variant into its own syntax.
+ *
+ * - `struct` — an inline anonymous type grouping named fields.
+ *   TypeScript renders as `{ petId: string; name?: string }`, Python as a `TypedDict` reference.
+ * - `member` — a single named field accessed from a named group type.
+ *   TypeScript renders as `PathParams['petId']`, C# as `PathParams.PetId`.
+ */
+export type TypeNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Type'
+} & (
+    | {
+        /**
+         * Reference variant — a plain type name or identifier.
+         * TypeScript renders as-is, e.g. `string`, `QueryParams`, `Partial<Config>`.
+         */
+        variant: 'reference'
+        /**
+         * The full type name string, e.g. `'string'`, `'QueryParams'`, `'Partial<Config>'`.
+         */
+        name: string
+      }
+    | {
+        /**
+         * Struct variant — an inline anonymous type grouping named fields.
+         * TypeScript renders as `{ key: Type; other?: OtherType }`.
+         */
+        variant: 'struct'
+        /**
+         * Properties of the struct type.
+         */
+        properties: Array<{ name: string; optional: boolean; type: TypeNode }>
+      }
+    | {
+        /**
+         * Member variant — a single named field accessed from a group type.
+         * TypeScript renders as `Base['key']`.
+         */
+        variant: 'member'
+        /**
+         * Base type name, e.g. `'DeletePetPathParams'`.
+         */
+        base: string
+        /**
+         * The field name to access, e.g. `'petId'`.
+         */
+        key: string
+      }
+  )
+
+/**
+ * AST node for one function parameter.
+ *
+ * @example Required parameter
+ * `name: Type`
+ *
+ * @example Optional parameter
+ * `name?: Type`
+ *
+ * @example Parameter with default value
+ * `name: Type = defaultValue`
+ *
+ * @example Rest parameter
+ * `...name: Type[]`
+ */
+export type FunctionParameterNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'FunctionParameter'
+  /**
+   * Parameter name in the generated signature.
+   */
+  name: string
+  /**
+   * Type annotation as a structured {@link TypeNode}.
+   * Omit for untyped output.
+   *
+   * @example Reference type node
+   * `{ kind: 'Type', variant: 'reference', name: 'string' }` → `petId: string`
+   *
+   * @example Struct type node
+   * `{ kind: 'Type', variant: 'struct', properties: [...] }` → `{ key: Type; other?: OtherType }`
+   *
+   * @example Member type node
+   * `{ kind: 'Type', variant: 'member', base: 'PathParams', key: 'petId' }` → `PathParams['petId']`
+   */
+  type?: TypeNode
+  /**
+   * When `true` the parameter is emitted as a rest parameter.
+   *
+   * @example Rest parameter
+   * `...name: Type[]`
+   */
+  rest?: boolean
+} /**
+ * Optional parameter — rendered with `?` and may be omitted by the caller.
+ * Cannot be combined with `default` because a defaulted parameter is already optional.
+ */ & (
+    | { optional: true; default?: never }
+    /**
+     * Required parameter, or a parameter with a default value.
+     *
+     * @example Required
+     * `name: Type`
+     *
+     * @example With default
+     * `name: Type = default`
+     */
+    | { optional?: false; default?: string }
+  )
+
+/**
+ * AST node for a group of related function parameters treated as a single unit.
+ *
+ * Each language printer decides how to render this group:
+ * - TypeScript/JS: destructured object `{ key1, key2 }: { key1: Type1; key2: Type2 } = {}`
+ * - Python: keyword-only args or a typed dict parameter
+ * - C# / Kotlin: named record / data-class parameter
+ *
+ * When `inline` is `true`, the group is spread as individual top-level parameters
+ * rather than wrapped in a single grouped construct.
+ *
+ * @example Grouped destructuring
+ * `{ id, name }: { id: string; name: string } = {}`
+ *
+ * @example Inline (spread as individual parameters)
+ * `id: string, name: string`
+ */
+export type ParameterGroupNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'ParameterGroup'
+  /**
+   * The individual parameters that form the group.
+   * Rendered as a destructured object or spread inline when `inline` is `true`.
+   */
+  properties: Array<FunctionParameterNode>
+  /**
+   * Optional explicit type annotation for the whole group.
+   * When absent, printers auto-compute it from `properties`.
+   */
+  type?: TypeNode
+  /**
+   * When `true`, `properties` are emitted as individual top-level parameters instead of
+   * being wrapped in a single grouped construct.
+   *
+   * @default false
+   */
+  inline?: boolean
+  /**
+   * Whether the group as a whole is optional.
+   * If omitted, printers infer this from child properties.
+   */
+  optional?: boolean
+  /**
+   * Default value for the group, written verbatim after `=`.
+   * Commonly `'{}'` to allow omitting the argument entirely.
+   */
+  default?: string
+}
+
+/**
+ * AST node for a complete function parameter list.
+ *
+ * Printers are responsible for sorting (`required` → `optional` → `defaulted`).
+ * Nodes are plain immutable data.
+ *
+ * Renders differently depending on the output mode:
+ * - `declaration` → `(id: string, config: Config = {})` — function declaration parameters
+ * - `call`        → `(id, { method, url })` — function call arguments
+ * - `keys`        → `{ id, config }` — key names only (for destructuring)
+ * - `values`      → `{ id: id, config: config }` — key → value pairs
+ */
+export type FunctionParametersNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'FunctionParameters'
+  /**
+   * Ordered parameter nodes.
+   */
+  params: ReadonlyArray<FunctionParameterNode | ParameterGroupNode>
+}
+
+/**
+ * The four function-signature AST node variants.
+ */
+export type FunctionNode = FunctionParameterNode | ParameterGroupNode | FunctionParametersNode | TypeNode
+
+/**
+ * Handler map keys — one per `FunctionNode` kind.
+ */
+export type FunctionNodeType = 'functionParameter' | 'parameterGroup' | 'functionParameters' | 'type'

package/src/nodes/http.ts

@@ -1,6 +1,6 @@
 /**
- * All IANA-registered HTTP status codes as string literals, matching how
- * they appear as keys in API specifications (e.g. `"200"`, `"404"`).
+ * All supported HTTP status code literals as strings, as used in API specs
+ * (for example, `"200"` and `"404"`).
  */
 export type HttpStatusCode =
   // 1xx Informational
@@ -72,13 +72,25 @@ export type HttpStatusCode =
   | '511'
 
 /**
- * A status code as used in an operation response: a specific HTTP status
- * code string or `"default"` as a catch-all fallback.
+ * Response status code literal used by operations.
+ *
+ * Includes specific HTTP status code strings and `"default"` for catch-all responses.
+ *
+ * @example
+ * ```ts
+ * const status: StatusCode = '200'
+ * const fallback: StatusCode = 'default'
+ * ```
  */
 export type StatusCode = HttpStatusCode | 'default'
 
 /**
- * Common IANA media types used in API request/response bodies.
+ * Supported media type strings used in request and response bodies.
+ *
+ * @example
+ * ```ts
+ * const mediaType: MediaType = 'application/json'
+ * ```
  */
 export type MediaType =
   // Application

package/src/nodes/index.ts

@@ -1,3 +1,4 @@
+import type { FunctionNode } from './function.ts'
 import type { OperationNode } from './operation.ts'
 import type { ParameterNode } from './parameter.ts'
 import type { PropertyNode } from './property.ts'
@@ -6,6 +7,7 @@ import type { RootNode } from './root.ts'
 import type { SchemaNode } from './schema.ts'
 
 export type { BaseNode, NodeKind } from './base.ts'
+export type { FunctionNode, FunctionNodeType, FunctionParameterNode, FunctionParametersNode, ParameterGroupNode, TypeNode } from './function.ts'
 export type { HttpStatusCode, MediaType, StatusCode } from './http.ts'
 export type { HttpMethod, OperationNode } from './operation.ts'
 export type { ParameterLocation, ParameterNode } from './parameter.ts'
@@ -19,7 +21,10 @@ export type {
   DatetimeSchemaNode,
   EnumSchemaNode,
   EnumValueNode,
+  FormatStringSchemaNode,
   IntersectionSchemaNode,
+  Ipv4SchemaNode,
+  Ipv6SchemaNode,
   NumberSchemaNode,
   ObjectSchemaNode,
   PrimitiveSchemaType,
@@ -33,13 +38,24 @@ export type {
   StringSchemaNode,
   TimeSchemaNode,
   UnionSchemaNode,
+  UrlSchemaNode,
 } from './schema.ts'
 
 /**
- * Discriminated union of every AST node.
+ * Union of all AST node types.
  *
- * Using a concrete union (instead of the bare `BaseNode` alias) lets
- * TypeScript narrow the type automatically inside `switch (node.kind)`
- * blocks, eliminating the need for manual `as TypeName` casts.
+ * This lets TypeScript narrow types in `switch (node.kind)` blocks.
+ *
+ * @example
+ * ```ts
+ * function getKind(node: Node): string {
+ *   switch (node.kind) {
+ *     case 'Root':
+ *       return 'root'
+ *     default:
+ *       return 'other'
+ *   }
+ * }
+ * ```
  */
-export type Node = RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode
+export type Node = RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode | FunctionNode

package/src/nodes/operation.ts

@@ -6,28 +6,91 @@ import type { SchemaNode } from './schema.ts'
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE'
 
 /**
- * A spec-agnostic representation of a single API operation.
+ * AST node representing one API operation.
+ *
+ * @example
+ * ```ts
+ * const operation: OperationNode = {
+ *   kind: 'Operation',
+ *   operationId: 'listPets',
+ *   method: 'GET',
+ *   path: '/pets',
+ *   tags: [],
+ *   parameters: [],
+ *   responses: [],
+ * }
+ * ```
  */
 export type OperationNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Operation'
   /**
-   * Unique operation identifier (maps to `operationId` in OAS).
+   * Operation identifier, usually from OpenAPI `operationId`.
    */
   operationId: string
+  /**
+   * HTTP Method like 'GET'
+   */
   method: HttpMethod
   /**
-   * Express-style path string, e.g. `/pets/:petId`.
-   * Derived from the OpenAPI path by converting `{param}` tokens to `:param`.
+   * OpenAPI-style path string, for example `/pets/{petId}`.
+   * Path parameters retain the `{param}` notation from the original spec.
    */
   path: string
+  /**
+   * Group labels for the operation.
+   * Usually copied from OpenAPI `tags`.
+   */
   tags: Array<string>
+  /**
+   * Short one-line operation summary.
+   */
   summary?: string
+  /**
+   * Full operation description.
+   */
   description?: string
+  /**
+   * Marks the operation as deprecated.
+   */
   deprecated?: boolean
+  /**
+   * Parameters that could be used, we have QueryParams, PathParams, HeaderParams and CookieParams
+   */
   parameters: Array<ParameterNode>
   /**
-   * Request body schema. For OAS, this is the schema of the first content entry.
+   * Request body metadata for the operation.
+   */
+  requestBody?: {
+    /**
+     * Human-readable request body description.
+     */
+    description?: string
+    /**
+     * Request body schema.
+     * For OpenAPI, this is the schema from the first `content` entry.
+     */
+    schema?: SchemaNode
+    /**
+     * Property keys to exclude from the generated request body type via `Omit<Type, Keys>`.
+     * Set when a referenced schema has `readOnly` fields that should be omitted in request types.
+     */
+    keysToOmit?: Array<string>
+    /**
+     * Whether the request body is required (`requestBody.required: true` in the spec).
+     * When `false` or absent, the generated `data` parameter should be optional.
+     */
+    required?: boolean
+    /**
+     * Media type of the request body (e.g. `'application/json'`, `'multipart/form-data'`).
+     * Extracted from the first `content` entry of the OpenAPI `requestBody`.
+     */
+    contentType?: string
+  }
+  /**
+   * Operation responses.
    */
-  requestBody?: SchemaNode
   responses: Array<ResponseNode>
 }

package/src/nodes/parameter.ts

@@ -4,12 +4,38 @@ import type { SchemaNode } from './schema.ts'
 export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie'
 
 /**
- * A single input parameter for an operation.
+ * AST node representing one operation parameter.
+ *
+ * @example
+ * ```ts
+ * const param: ParameterNode = {
+ *   kind: 'Parameter',
+ *   name: 'petId',
+ *   in: 'path',
+ *   schema: createSchema({ type: 'string' }),
+ *   required: true,
+ * }
+ * ```
  */
 export type ParameterNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Parameter'
+  /**
+   * Parameter name.
+   */
   name: string
+  /**
+   * Parameter location (`path`, `query`, `header`, or `cookie`).
+   */
   in: ParameterLocation
+  /**
+   * Parameter schema.
+   */
   schema: SchemaNode
+  /**
+   * Whether the parameter is required.
+   */
   required: boolean
 }