openapi-typesafe 0.0.0 → 1.0.0-rc.0

package/src/types/generator-options.ts

@@ -0,0 +1,267 @@
+import type { PathLike } from "node:fs";
+import type { Readable } from "node:stream";
+import type { Config as RedoclyConfig } from "@redocly/openapi-core";
+import type { ts } from "../adapters/type-ast-bridge/typescript-types.js";
+import type { FooterEntry } from "../api/footer-entry.js";
+import type { Logger } from "../application/ports/logger.js";
+import type { DocumentFooter } from "../application/transform/transform-context.js";
+import type { IrPropertySignature, IrType } from "../domain/ir/nodes.js";
+import type { OutputFix, OutputFixName } from "../domain/output-fixes.js";
+import type { ReferenceObject } from "./openapi-common.js";
+import type { OpenAPI3 } from "./openapi-document.js";
+import type { DiscriminatorObject, SchemaObject } from "./openapi-schema.js";
+
+export interface TransformObject {
+  /** The type: an IR type (from the helpers), or a TypeScript node (read by the bridge). */
+  schema: IrType | ts.TypeNode;
+  questionToken: boolean;
+}
+
+/**
+ * Every source type `openapiTS` accepts: YAML or JSON text, a URL, a parsed document, bytes or a
+ * stream.
+ */
+export type SchemaSource = string | URL | OpenAPI3 | Buffer | Readable;
+
+/** The generator options other than the schema callbacks. */
+export interface OpenAPITSBaseOptions {
+  /** Treat all objects as if they have `additionalProperties: true` by default (default: false) */
+  additionalProperties?: boolean;
+  /** Alphabetize all keys? (default: false) */
+  alphabetize?: boolean;
+  /** (optional) Generate tuples using array minItems / maxItems */
+  arrayLength?: boolean;
+  /**
+   * Type raw binary strings as `Blob` instead of `string` (default: false): `format: binary`
+   * (OpenAPI 3.0), or a `contentMediaType` that is not text and has no `contentEncoding` (3.1).
+   * `Blob` is a global type of the DOM lib and `@types/node`.
+   */
+  binaryAsBlob?: boolean;
+  /**
+   * Allow schema objects with no specified properties to have additional properties if not
+   * expressly forbidden? (default: false)
+   */
+  emptyObjectsUnknown?: boolean;
+  /** Provide current working directory (cwd) which helps resolve relative remote schemas */
+  cwd?: PathLike;
+  /**
+   * Load local `$ref` files only from this directory and below it; a relative path resolves
+   * against `cwd`. Default: no limit. Threat model R1, ADR-017.
+   */
+  localRefRoot?: string | URL;
+  /**
+   * Load remote `$ref` documents only from these hosts (`name` or `name:port`); `[]` loads none.
+   * Redirects are checked too. Default: any host. Threat model R2, ADR-017.
+   */
+  remoteRefHosts?: readonly string[];
+  /** Should schema objects with a default value not be considered optional? */
+  defaultNonNullable?: boolean;
+  /** Exclude deprecated fields from types? (default: false) */
+  excludeDeprecated?: boolean;
+  /**
+   * Opt-in fixes of the output of valid schemas (default: none), ADR-021. `"all"` turns on every
+   * fix of the installed version, so a minor update can change the output; list the names to keep
+   * it stable. An unknown name fails with `OPTION_FIX_UNKNOWN`.
+   * @see https://github.com/openapi-typesafe/openapi-typesafe/blob/main/docs/cli.md#fix
+   */
+  fix?: readonly OutputFixName[];
+  /** Add readonly properties and readonly arrays? (default: false) */
+  immutable?: boolean;
+  /**
+   * Lint the document with the Redocly config before generating (default: true). Bundling errors
+   * still fail the run.
+   */
+  lint?: boolean;
+  /** (optional) Should logging be suppressed? (necessary for STDOUT) */
+  silent?: boolean;
+  /** (optional) OpenAPI version. Must be present if parsing raw schema */
+  version?: number;
+  /** (optional) Export type instead of interface */
+  exportType?: boolean;
+  /** Export true TypeScript enums instead of unions */
+  enum?: boolean;
+  /** Export union values as arrays */
+  enumValues?: boolean;
+  /** Only generate TS Enums when `x-enum-*` metadata is available */
+  conditionalEnums?: boolean;
+  /** Dedupe enum values */
+  dedupeEnums?: boolean;
+  /** (optional) Substitute path parameter names with their respective types */
+  pathParamsAsTypes?: boolean;
+  /**
+   * Treat all objects as if they have \`required\` set to all properties by default (default:
+   * false)
+   */
+  propertiesRequiredByDefault?: boolean;
+  /** (optional) Generate schema types at root level */
+  rootTypes?: boolean;
+  /** (optional) Do not add Schema prefix to types at root level */
+  rootTypesNoSchemaPrefix?: boolean;
+  /** (optional) Keep casing of root types */
+  rootTypesKeepCasing?: boolean;
+  /**
+   * Configure Redocly for validation, schema fetching, and bundling
+   * @see https://redocly.com/docs/cli/configuration/
+   */
+  redocly?: RedoclyConfig;
+  /** Inject arbitrary TypeScript types into the start of the file */
+  inject?: string;
+  /** Generate ApiPaths enum */
+  makePathsEnum?: boolean;
+  /** Generate path params based on path even if they are not defined in the open api schema */
+  generatePathParams?: boolean;
+  /** Generate $Read/$Write markers for readOnly/writeOnly properties (default: false) */
+  readWriteMarkers?: boolean;
+}
+
+/**
+ * The schema callbacks of the original API: they receive TypeScript nodes (ADR-004, decisions 5
+ * and 6). Results may be IR (from the helpers) or TypeScript nodes, read by the bridge.
+ */
+export interface LegacyCallbackOptions {
+  /** Unset or false: the callbacks below receive TypeScript nodes. */
+  irCallbacks?: false;
+  /** Manually transform certain Schema Objects with a custom TypeScript type */
+  transform?: (
+    schemaObject: SchemaObject,
+    options: TransformNodeOptions,
+  ) => IrType | ts.TypeNode | TransformObject | undefined;
+  /**
+   * Modify TypeScript types built from Schema Objects (receives a TypeScript node)
+   * @deprecated Use `irCallbacks: true` (ADR-004, decision 6); the TypeScript form is removed in
+   * 2.0.
+   */
+  postTransform?: (
+    type: ts.TypeNode,
+    options: TransformNodeOptions,
+  ) => IrType | ts.TypeNode | undefined;
+  /**
+   * Modify property signatures for Schema Object properties (receives a TypeScript node)
+   * @deprecated Use `irCallbacks: true` (ADR-004, decision 6); the TypeScript form is removed in
+   * 2.0.
+   */
+  transformProperty?: (
+    property: ts.PropertySignature,
+    schemaObject: SchemaObject,
+    options: TransformNodeOptions,
+  ) => IrPropertySignature | ts.PropertySignature | undefined;
+}
+
+/**
+ * The schema callbacks that have a deprecated TypeScript-node form (ADR-004, decisions 5 and 6).
+ */
+export type LegacyCallbackName = "transform" | "postTransform" | "transformProperty";
+
+/** A type an IR callback returns: an IR type, or TypeScript type text printed as written. */
+export type IrCallbackType = IrType | string;
+
+/** What an IR `transform` callback returns to make the property optional. */
+export interface IrTransformObject {
+  schema: IrCallbackType;
+  questionToken: boolean;
+}
+
+/** Replace the generated type of a Schema Object; `undefined` keeps the generated type. */
+export type IrTransform = (
+  schemaObject: SchemaObject,
+  options: TransformNodeOptions,
+) => IrCallbackType | IrTransformObject | undefined;
+
+/** Modify the generated type of a Schema Object; `undefined` keeps it. */
+export type IrPostTransform = (
+  type: IrType,
+  options: TransformNodeOptions,
+) => IrCallbackType | undefined;
+
+/** Modify the generated property of a Schema Object property; `undefined` keeps it. */
+export type IrTransformProperty = (
+  property: IrPropertySignature,
+  schemaObject: SchemaObject,
+  options: TransformNodeOptions,
+) => IrPropertySignature | undefined;
+
+/** The schema callbacks on IR (ENGINEERING_PLAN 6.3): they receive and return IR nodes. */
+export interface IrCallbackOptions {
+  irCallbacks: true;
+  transform?: IrTransform;
+  postTransform?: IrPostTransform;
+  transformProperty?: IrTransformProperty;
+}
+
+/** The options of the original API: callbacks on TypeScript nodes. */
+export interface OpenAPITSOptions extends OpenAPITSBaseOptions, LegacyCallbackOptions {}
+
+/** The options with `irCallbacks: true`: callbacks on IR nodes. */
+export interface OpenAPITSIrOptions extends OpenAPITSBaseOptions, IrCallbackOptions {}
+
+/** Either form of the generator options. */
+export type GeneratorOptions = OpenAPITSOptions | OpenAPITSIrOptions;
+
+/** Context passed to all submodules */
+export interface GlobalContext {
+  // user options
+  additionalProperties: boolean;
+  alphabetize: boolean;
+  arrayLength: boolean;
+  binaryAsBlob: boolean;
+  defaultNonNullable: boolean;
+  discriminators: {
+    objects: Record<string, DiscriminatorObject>;
+    refsHandled: string[];
+  };
+  emptyObjectsUnknown: boolean;
+  enum: boolean;
+  enumValues: boolean;
+  conditionalEnums: boolean;
+  dedupeEnums: boolean;
+  excludeDeprecated: boolean;
+  exportType: boolean;
+  /** The opt-in output fixes of this run, `all` expanded (ADR-021). Unset: none. */
+  fix?: readonly OutputFix[];
+  immutable: boolean;
+  /**
+   * Declarations written after the main types, in order. The generator adds IR declarations;
+   * callbacks may add IR declarations or TypeScript nodes.
+   */
+  injectFooter: FooterEntry[];
+  /**
+   * @internal Footer state of this run (enum registry and enum naming), created on first use by
+   * the transform context adapter. Not an option; do not set it.
+   */
+  runFooter?: DocumentFooter;
+  /**
+   * @internal The deprecated callback forms this run has warned about (once each). Not an
+   * option; do not set it.
+   */
+  legacyCallbackWarnings?: Set<LegacyCallbackName>;
+  /**
+   * @internal Where this run reports warnings and debug output. Not an option; a context without
+   * it logs to the terminal.
+   */
+  logger?: Logger;
+  pathParamsAsTypes: boolean;
+  /** Whether the callbacks below take IR (`OpenAPITSIrOptions`) or TypeScript nodes. */
+  irCallbacks: boolean;
+  postTransform: GeneratorOptions["postTransform"];
+  propertiesRequiredByDefault: boolean;
+  rootTypes: boolean;
+  rootTypesNoSchemaPrefix: boolean;
+  rootTypesKeepCasing: boolean;
+  redoc: RedoclyConfig;
+  silent: boolean;
+  transform: GeneratorOptions["transform"];
+  transformProperty: GeneratorOptions["transformProperty"];
+  /** retrieve a node by $ref */
+  resolve<T>($ref: string): T | undefined;
+  inject?: string;
+  makePathsEnum: boolean;
+  generatePathParams: boolean;
+  readWriteMarkers: boolean;
+}
+
+/** generic options for most internal transform* functions */
+export interface TransformNodeOptions {
+  path?: string;
+  schema?: SchemaObject | ReferenceObject;
+  ctx: GlobalContext;
+}

package/src/types/openapi-common.ts

@@ -0,0 +1,100 @@
+// Many types allow for true “any” for inheritance to work
+
+// Note: these OpenAPI types are meant only for internal use, not external
+// consumption. Some formatting may be better in other libraries meant for
+// consumption. Some typing may be “loose” or “incorrect” in order to guarantee
+// that all logical paths are handled. In other words, these are built more
+// for ways schemas _can_ be written, not necessarily how they _should_ be.
+
+export interface Extensable {
+  [key: `x-${string}`]: any;
+}
+
+// Note: these OpenAPI types are meant only for internal use, not external
+// consumption. Some formatting may be better in other libraries meant for
+// consumption. Some typing may be “loose” or “incorrect” in order to guarantee
+// that all logical paths are handled. In other words, these are built more
+// for ways schemas _can_ be written, not necessarily how they _should_ be.
+
+/**
+ * [4.8.5] Server Object
+ * An object representing a Server.
+ */
+export interface ServerObject extends Extensable {
+  /**
+   * REQUIRED. A URL to the target host. This URL supports Server Variables and MAY be relative, to
+   * indicate that the host location is relative to the location where the OpenAPI document is being
+   * served. Variable substitutions will be made when a variable is named in {brackets}.
+   */
+  url: string;
+  /**
+   * An optional string describing the host designated by the URL. CommonMark syntax MAY be used for
+   * rich text representation.
+   */
+  description: string;
+  /**
+   * A map between a variable name and its value. The value is used for substitution in the server’s
+   * URL template.
+   */
+  variables: { [name: string]: ServerVariableObject };
+}
+
+/**
+ * [4.8.6] Server Variable Object
+ * An object representing a Server Variable for server URL template substitution.
+ */
+export interface ServerVariableObject extends Extensable {
+  /**
+   * An enumeration of string values to be used if the substitution options are from a limited set.
+   * The array MUST NOT be empty.
+   */
+  enum?: string[];
+  /**
+   * REQUIRED. The default value to use for substitution, which SHALL be sent if an alternate value
+   * is not supplied. Note this behavior is different than the Schema Object’s treatment of default
+   * values, because in those cases parameter values are optional. If the enum is defined, the value
+   * MUST exist in the enum’s values.
+   */
+  default: string;
+  /**
+   * An optional description for the server variable. CommonMark syntax MAY be used for rich text
+   * representation.
+   */
+  description?: string;
+}
+
+/**
+ * [4.8.11] External Documentation Object
+ * Allows referencing an external resource for extended documentation.
+ */
+export interface ExternalDocumentationObject extends Extensable {
+  /**
+   * A description of the target documentation. CommonMark syntax MAY be used for rich text
+   * representation.
+   */
+  description?: string;
+  /** REQUIRED. The URL for the target documentation. This MUST be in the form of a URL. */
+  url: string;
+}
+
+/**
+ * [4.8.23] Reference Object
+ * A simple object to allow referencing other components in the OpenAPI document, internally and
+ * externally. The $ref string value contains a URI [RFC3986], which identifies the location of the
+ * value being referenced. See the rules for resolving Relative References.
+ */
+export interface ReferenceObject extends Extensable {
+  /** REQUIRED. The reference identifier. This MUST be in the form of a URI. */
+  $ref: string;
+  /**
+   * A short summary which by default SHOULD override that of the referenced component. If the
+   * referenced object-type does not allow a summary field, then this field has no effect.
+   */
+  summary?: string;
+  /**
+   * A description which by default SHOULD override that of the referenced component. CommonMark
+   * syntax MAY be used for rich text representation. If the referenced object-type does not allow a
+   * description field, then this field has no effect.
+   */
+  description?: string;
+}

package/src/types/openapi-document.ts

@@ -0,0 +1,196 @@
+import type {
+  Extensable,
+  ExternalDocumentationObject,
+  ReferenceObject,
+  ServerObject,
+} from "./openapi-common.js";
+import type { CallbackObject, PathItemObject } from "./openapi-path-item.js";
+import type {
+  ExampleObject,
+  HeaderObject,
+  MediaTypeObject,
+  ParameterObject,
+  RequestBodyObject,
+} from "./openapi-request.js";
+import type { LinkObject, ResponseObject } from "./openapi-response.js";
+import type { $defs, SchemaObject } from "./openapi-schema.js";
+import type { SecurityRequirementObject, SecuritySchemeObject } from "./openapi-security.js";
+
+/**
+ * [4.8] Schema
+ * @see https://spec.openapis.org/oas/v3.1.0#schema
+ */
+export interface OpenAPI3 extends Extensable {
+  /**
+   * REQUIRED. This string MUST be the version number of the OpenAPI Specification that the OpenAPI
+   * document uses. The openapi field SHOULD be used by tooling to interpret the OpenAPI document.
+   * This is not related to the API info.version string.
+   */
+  openapi: string;
+  /** REQUIRED. Provides metadata about the API. The metadata MAY be used by tooling as required. */
+  info: InfoObject; // required
+  /**
+   * The default value for the $schema keyword within Schema Objects contained within this OAS
+   * document. This MUST be in the form of a URI.
+   */
+  jsonSchemaDialect?: string;
+  /**
+   * An array of Server Objects, which provide connectivity information to a target server. If the
+   * servers property is not provided, or is an empty array, the default value would be a Server
+   * Object with a url value of /.
+   */
+  servers?: ServerObject[];
+  /** The available paths and operations for the API. */
+  paths?: PathsObject;
+  /**
+   * The incoming webhooks that MAY be received as part of this API and that the API consumer MAY
+   * choose to implement. Closely related to the callbacks feature, this section describes requests
+   * initiated other than by an API call, for example by an out of band registration. The key name
+   * is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object
+   * describes a request that may be initiated by the API provider and the expected responses. An
+   * example is available.
+   */
+  webhooks?: { [id: string]: PathItemObject | ReferenceObject };
+  /** An element to hold various schemas for the document. */
+  components?: ComponentsObject;
+  /**
+   * A declaration of which security mechanisms can be used across the API. The list of values
+   * includes alternative security requirement objects that can be used. Only one of the security
+   * requirement objects need to be satisfied to authorize a request. Individual operations can
+   * override this definition. To make security optional, an empty security requirement ({}) can be
+   * included in the array.
+   */
+  security?: SecurityRequirementObject[];
+  /**
+   * A list of tags used by the document with additional metadata. The order of the tags can be used
+   * to reflect on their order by the parsing tools. Not all tags that are used by the Operation
+   * Object must be declared. The tags that are not declared MAY be organized randomly or based on
+   * the tools’ logic. Each tag name in the list MUST be unique.
+   */
+  tags?: TagObject[];
+  /** Additional external documentation. */
+  externalDocs?: ExternalDocumentationObject;
+  $defs?: $defs;
+}
+
+/**
+ * [4.8.2] Info Object
+ * The object provides metadata about the API.
+ */
+export interface InfoObject extends Extensable {
+  /** REQUIRED. The title of the API. */
+  title: string;
+  /** A short summary of the API. */
+  summary?: string;
+  /** A description of the API. CommonMark syntax MAY be used for rich text representation. */
+  description?: string;
+  /** A URL to the Terms of Service for the API. This MUST be in the form of a URL. */
+  termsOfService?: string;
+  /** The contact information for the exposed API. */
+  contact?: ContactObject;
+  /** The license information for the exposed API. */
+  license?: LicenseObject;
+  /**
+   * REQUIRED. The version of the OpenAPI document (which is distinct from the OpenAPI Specification
+   * version or the API implementation version).
+   */
+  version: string;
+}
+
+/**
+ * [4.8.3] Contact Object
+ * Contact information for the exposed API.
+ */
+export interface ContactObject extends Extensable {
+  /** The identifying name of the contact person/organization. */
+  name?: string;
+  /** The URL pointing to the contact information. This MUST be in the form of a URL. */
+  url?: string;
+  /**
+   * The email address of the contact person/organization. This MUST be in the form of an email
+   * address.
+   */
+  email?: string;
+}
+
+/**
+ * [4.8.4] License object
+ * License information for the exposed API.
+ */
+export interface LicenseObject extends Extensable {
+  /** REQUIRED. The license name used for the API. */
+  name: string;
+  /**
+   * An SPDX license expression for the API. The identifier field is mutually exclusive of the url
+   * field.
+   */
+  identifier: string;
+  /**
+   * A URL to the license used for the API. This MUST be in the form of a URL. The url field is
+   * mutually exclusive of the identifier field.
+   */
+  url: string;
+}
+
+/**
+ * [4.8.7] Components Object
+ * Holds a set of reusable objects for different aspects of the OAS.
+ */
+export interface ComponentsObject extends Extensable {
+  /** An object to hold reusable Schema Objects.*/
+  schemas?: Record<string, SchemaObject>;
+  /** An object to hold reusable Response Objects. */
+  responses?: Record<string, ResponseObject | ReferenceObject>;
+  /** An object to hold reusable Parameter Objects. */
+  parameters?: Record<string, ParameterObject | ReferenceObject>;
+  /** An object to hold reusable Example Objects. */
+  examples?: Record<string, ExampleObject | ReferenceObject>;
+  /** An object to hold reusable Request Body Objects. */
+  requestBodies?: Record<string, RequestBodyObject | ReferenceObject>;
+  /** An object to hold reusable Header Objects. */
+  headers?: Record<string, HeaderObject | ReferenceObject>;
+  /** An object to hold reusable Security Scheme Objects. */
+  securitySchemes?: Record<string, SecuritySchemeObject | ReferenceObject>;
+  /** An object to hold reusable Link Objects. */
+  links?: Record<string, LinkObject | ReferenceObject>;
+  /** An object to hold reusable Callback Objects. */
+  callbacks?: Record<string, CallbackObject | ReferenceObject>;
+  /** An object to hold reusable Path Item Objects. */
+  pathItems?: Record<string, PathItemObject | ReferenceObject>;
+  /** An object to hold reusable Media Type Objects (OpenAPI 3.2). */
+  mediaTypes?: Record<string, MediaTypeObject | ReferenceObject>;
+}
+
+/**
+ * [4.8.8] Paths Object
+ * Holds the relative paths to the individual endpoints and their operations. The path is appended
+ * to the URL from the Server Object in order to construct the full URL. The Paths MAY be empty, due
+ * to Access Control List (ACL) constraints.
+ */
+export interface PathsObject {
+  // note: paths object does support $refs; the schema just defines it in a weird way
+  [pathname: string]: PathItemObject | ReferenceObject;
+}
+
+/**
+ * [x.x.x] Webhooks Object
+ * Holds the webhooks definitions, indexed by their names. A webhook is defined by a Path Item
+ * Object; the only difference is that the request is initiated by the API provider.
+ */
+export interface WebhooksObject {
+  [name: string]: PathItemObject;
+}
+
+/**
+ * [4.8.22] Tag Object
+ * Adds metadata to a single tag that is used by the Operation Object. It is not mandatory to have a
+ * Tag Object per tag defined in the Operation Object instances.
+ */
+export interface TagObject extends Extensable {
+  /** REQUIRED. The name of the tag. */
+  name: string;
+  /** A description for the tag. CommonMark syntax MAY be used for rich text representation. */
+  description?: string;
+  /** Additional external documentation for this tag. */
+  externalDocs?: ExternalDocumentationObject;
+}

package/src/types/openapi-path-item.ts

@@ -0,0 +1,130 @@
+import type {
+  Extensable,
+  ExternalDocumentationObject,
+  ReferenceObject,
+  ServerObject,
+} from "./openapi-common.js";
+import type { ParameterObject, RequestBodyObject } from "./openapi-request.js";
+import type { ResponsesObject } from "./openapi-response.js";
+import type { SecurityRequirementObject } from "./openapi-security.js";
+
+/**
+ * [4.8.9] Path Item Object
+ * Describes the operations available on a single path. A Path Item MAY be empty, due to ACL
+ * constraints. The path itself is still exposed to the documentation viewer but they will not know
+ * which operations and parameters are available.
+ */
+export interface PathItemObject extends Extensable {
+  /** A definition of a GET operation on this path. */
+  get?: OperationObject | ReferenceObject;
+  /** A definition of a PUT operation on this path. */
+  put?: OperationObject | ReferenceObject;
+  /** A definition of a POST operation on this path. */
+  post?: OperationObject | ReferenceObject;
+  /** A definition of a DELETE operation on this path. */
+  delete?: OperationObject | ReferenceObject;
+  /** A definition of a OPTIONS operation on this path. */
+  options?: OperationObject | ReferenceObject;
+  /** A definition of a HEAD operation on this path. */
+  head?: OperationObject | ReferenceObject;
+  /** A definition of a PATCH operation on this path. */
+  patch?: OperationObject | ReferenceObject;
+  /** A definition of a TRACE operation on this path. */
+  trace?: OperationObject | ReferenceObject;
+  /** A definition of a QUERY operation on this path (OpenAPI 3.2). */
+  query?: OperationObject | ReferenceObject;
+  /**
+   * Operations for other HTTP methods, keyed by the method name exactly as it is sent
+   * (OpenAPI 3.2). The fixed methods above must not appear here.
+   */
+  additionalOperations?: Record<string, OperationObject | ReferenceObject>;
+  /** An alternative server array to service all operations in this path. */
+  servers?: ServerObject[];
+  /**
+   * A list of parameters that are applicable for all the operations described under this path.
+   * These parameters can be overridden at the operation level, but cannot be removed there. The
+   * list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of
+   * a name and location. The list can use the Reference Object to link to parameters that are
+   * defined at the OpenAPI Object’s components/parameters.
+   */
+  parameters?: (ParameterObject | ReferenceObject)[];
+}
+
+/**
+ * [4.8.10] Operation Object
+ * Describes a single API operation on a path.
+ */
+export interface OperationObject extends Extensable {
+  /**
+   * A list of tags for API documentation control. Tags can be used for logical grouping of
+   * operations by resources or any other qualifier.
+   */
+  tags?: string[];
+  /** A short summary of what the operation does. */
+  summary?: string;
+  /**
+   * A verbose explanation of the operation behavior. CommonMark syntax MAY be used for rich text
+   * representation.
+   */
+  description?: string;
+  /** Additional external documentation for this operation. */
+  externalDocs?: ExternalDocumentationObject;
+  /**
+   * Unique string used to identify the operation. The id MUST be unique among all operations
+   * described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the
+   * operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common
+   * programming naming conventions.
+   */
+  operationId?: string;
+  /**
+   * A list of parameters that are applicable for this operation. If a parameter is already defined
+   * at the Path Item, the new definition will override it but can never remove it. The list MUST
+   * NOT include duplicated parameters. A unique parameter is defined by a combination of a name and
+   * location. The list can use the Reference Object to link to parameters that are defined at the
+   * OpenAPI Object’s components/parameters.
+   */
+  parameters?: (ParameterObject | ReferenceObject)[];
+  /**
+   * The request body applicable for this operation. The requestBody is fully supported in HTTP
+   * methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request
+   * bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody
+   * is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
+   */
+  requestBody?: RequestBodyObject | ReferenceObject;
+  /** The list of possible responses as they are returned from executing this operation. */
+  responses?: ResponsesObject;
+  /**
+   * A map of possible out-of band callbacks related to the parent operation. The key is a unique
+   * identifier for the Callback Object. Each value in the map is a Callback Object that describes a
+   * request that may be initiated by the API provider and the expected responses.
+   */
+  callbacks?: Record<string, CallbackObject | ReferenceObject>;
+  /**
+   * Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared
+   * operation. Default value is false.
+   */
+  deprecated?: boolean;
+  /**
+   * A declaration of which security mechanisms can be used for this operation. The list of values
+   * includes alternative security requirement objects that can be used. Only one of the security
+   * requirement objects need to be satisfied to authorize a request. To make security optional, an
+   * empty security requirement ({}) can be included in the array. This definition overrides any
+   * declared top-level security. To remove a top-level security declaration, an empty array can be
+   * used.
+   */
+  security?: SecurityRequirementObject[];
+  /**
+   * An alternative server array to service this operation. If an alternative server object is
+   * specified at the Path Item Object or Root level, it will be overridden by this value.
+   */
+  servers?: ServerObject[];
+}
+
+/**
+ * [4.8.18] Callback Object
+ * A map of possible out-of band callbacks related to the parent operation. Each value in the map is
+ * a Path Item Object that describes a set of requests that may be initiated by the API provider and
+ * the expected responses. The key value used to identify the path item object is an expression,
+ * evaluated at runtime, that identifies a URL to use for the callback operation.
+ */
+export type CallbackObject = Record<string, PathItemObject>;