@typia/interface 12.0.0-dev.20260225

package/lib/openapi/OpenApi.d.ts

@@ -0,0 +1,454 @@
+import { IJsonSchemaAttribute } from "../schema/IJsonSchemaAttribute";
+import * as tags from "../tags";
+/**
+ * Emended OpenAPI v3.1 specification.
+ *
+ * `OpenApi` is a refined OpenAPI v3.1 specification that normalizes ambiguous
+ * and redundant expressions from various OpenAPI versions (Swagger 2.0, OpenAPI
+ * 3.0, 3.1). This unified format simplifies schema processing for `typia` and
+ * `@nestia/sdk`.
+ *
+ * Key simplifications:
+ *
+ * - Schema `$ref` references are unified to `#/components/schemas/{name}` format
+ * - Non-schema references (parameters, responses) are resolved inline
+ * - `nullable` is converted to `{ oneOf: [schema, { type: "null\" }] }`
+ * - `allOf` compositions are merged into single schemas
+ * - Schema attributes are normalized across all versions
+ *
+ * Use `HttpLlm.application()` from `@typia/utils` to convert
+ * `OpenApi.IDocument` into {@link IHttpLlmApplication} for LLM function
+ * calling.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare namespace OpenApi {
+    /**
+     * HTTP method supported by OpenAPI operations.
+     *
+     * Standard HTTP methods used in REST APIs. Each path can have multiple
+     * operations, one per HTTP method.
+     */
+    type Method = "get" | "post" | "put" | "delete" | "options" | "head" | "patch" | "trace";
+    /**
+     * Root document structure for emended OpenAPI v3.1.
+     *
+     * Contains all API metadata, paths, operations, and reusable components. The
+     * `x-samchon-emended-v4` marker indicates this document has been processed by
+     * `@samchon/openapi` to normalize schema formats.
+     */
+    interface IDocument {
+        /** OpenAPI version. */
+        openapi: `3.1.${number}`;
+        /** List of servers providing the API. */
+        servers?: IServer[];
+        /** API metadata. */
+        info?: IDocument.IInfo;
+        /** Reusable components (schemas, security schemes). */
+        components: IComponents;
+        /** Available API paths and operations. */
+        paths?: Record<string, IPath>;
+        /** Webhook definitions. */
+        webhooks?: Record<string, IPath>;
+        /** Global security requirements. */
+        security?: Record<string, string[]>[];
+        /** Tag definitions for grouping operations. */
+        tags?: IDocument.ITag[];
+        /** Marker for emended document by `@samchon/openapi`. */
+        "x-samchon-emended-v4": true;
+    }
+    namespace IDocument {
+        /**
+         * API metadata and identification.
+         *
+         * Contains essential information about the API including title, version,
+         * contact information, and licensing details.
+         */
+        interface IInfo {
+            /** API title. */
+            title: string;
+            /** Short summary. */
+            summary?: string;
+            /** Full description. */
+            description?: string;
+            /** Terms of service URL. */
+            termsOfService?: string;
+            /** Contact information. */
+            contact?: IContact;
+            /** License information. */
+            license?: ILicense;
+            /** API version. */
+            version: string;
+        }
+        /** Tag for grouping operations. */
+        interface ITag {
+            /** Tag name. */
+            name: string;
+            /** Tag description. */
+            description?: string;
+        }
+        /** Contact information. */
+        interface IContact {
+            /** Contact name. */
+            name?: string;
+            /** Contact URL. */
+            url?: string;
+            /** Contact email. */
+            email?: string & tags.Format<"email">;
+        }
+        /** License information. */
+        interface ILicense {
+            /** License name. */
+            name: string;
+            /** SPDX license identifier. */
+            identifier?: string;
+            /** License URL. */
+            url?: string;
+        }
+    }
+    /** Server providing the API. */
+    interface IServer {
+        /** Server URL. */
+        url: string;
+        /** Server description. */
+        description?: string;
+        /** URL template variables. */
+        variables?: Record<string, IServer.IVariable>;
+    }
+    namespace IServer {
+        /** URL template variable. */
+        interface IVariable {
+            /** Default value. */
+            default: string;
+            /** Allowed values. */
+            enum?: string[];
+            /** Variable description. */
+            description?: string;
+        }
+    }
+    /** Path item containing operations by HTTP method. */
+    interface IPath extends Partial<Record<Method, IOperation>> {
+        /** Path-level servers. */
+        servers?: IServer[];
+        /** Path summary. */
+        summary?: string;
+        /** Path description. */
+        description?: string;
+    }
+    /** API operation metadata. */
+    interface IOperation {
+        /** Unique operation identifier. */
+        operationId?: string;
+        /** Operation parameters. */
+        parameters?: IOperation.IParameter[];
+        /** Request body. */
+        requestBody?: IOperation.IRequestBody;
+        /** Response definitions by status code. */
+        responses?: Record<string, IOperation.IResponse>;
+        /** Operation-level servers. */
+        servers?: IServer[];
+        /** Short summary. */
+        summary?: string;
+        /** Full description. */
+        description?: string;
+        /** Security requirements. */
+        security?: Record<string, string[]>[];
+        /** Operation tags for grouping. */
+        tags?: string[];
+        /** Whether deprecated. */
+        deprecated?: boolean;
+        /** Excludes from LLM function calling when `true`. */
+        "x-samchon-human"?: boolean;
+        /** Custom accessor path for migration. */
+        "x-samchon-accessor"?: string[];
+        /** Controller name for code generation. */
+        "x-samchon-controller"?: string;
+    }
+    namespace IOperation {
+        /** Operation parameter. */
+        interface IParameter {
+            /** Parameter name. */
+            name?: string;
+            /** Parameter location. */
+            in: "path" | "query" | "header" | "cookie";
+            /** Parameter schema. */
+            schema: IJsonSchema;
+            /** Whether required. */
+            required?: boolean;
+            /** Parameter description. */
+            description?: string;
+            /** Example value. */
+            example?: any;
+            /** Named examples. */
+            examples?: Record<string, IExample>;
+        }
+        /** Request body. */
+        interface IRequestBody {
+            /** Body content by media type. */
+            content?: IContent;
+            /** Body description. */
+            description?: string;
+            /** Whether required. */
+            required?: boolean;
+            /** Nestia encryption flag. */
+            "x-nestia-encrypted"?: boolean;
+        }
+        /** Response definition. */
+        interface IResponse {
+            /** Response headers. */
+            headers?: Record<string, IOperation.IParameter>;
+            /** Response content by media type. */
+            content?: IContent;
+            /** Response description. */
+            description?: string;
+            /** Nestia encryption flag. */
+            "x-nestia-encrypted"?: boolean;
+        }
+        /** Content by media type. */
+        interface IContent extends Partial<Record<ContentType, IMediaType>> {
+        }
+        /** Media type definition. */
+        interface IMediaType {
+            /** Content schema. */
+            schema?: IJsonSchema;
+            /** Example value. */
+            example?: any;
+            /** Named examples. */
+            examples?: Record<string, IExample>;
+        }
+        /** Supported content types. */
+        type ContentType = "text/plain" | "application/json" | "application/x-www-form-url-encoded" | "multipart/form-data" | "*/*" | (string & {});
+    }
+    /** Example value definition. */
+    interface IExample {
+        /** Example summary. */
+        summary?: string;
+        /** Example description. */
+        description?: string;
+        /** Example value. */
+        value?: any;
+        /** External value URL. */
+        externalValue?: string;
+    }
+    /** Reusable components storage. */
+    interface IComponents {
+        /** Named schemas. */
+        schemas?: Record<string, IJsonSchema>;
+        /** Named security schemes. */
+        securitySchemes?: Record<string, ISecurityScheme>;
+    }
+    /**
+     * JSON Schema type for emended OpenAPI v3.1.
+     *
+     * Represents all possible JSON Schema types in the normalized OpenAPI format.
+     * This is a discriminated union - check the `type` property or use type
+     * guards to narrow to specific schema types.
+     *
+     * Unlike raw JSON Schema, this format:
+     *
+     * - Uses `oneOf` instead of `anyOf` for union types
+     * - Separates `IArray` (homogeneous) from `ITuple` (heterogeneous)
+     * - Normalizes nullable types to `oneOf` with null schema
+     */
+    type IJsonSchema = IJsonSchema.IConstant | IJsonSchema.IBoolean | IJsonSchema.IInteger | IJsonSchema.INumber | IJsonSchema.IString | IJsonSchema.IArray | IJsonSchema.ITuple | IJsonSchema.IObject | IJsonSchema.IReference | IJsonSchema.IOneOf | IJsonSchema.INull | IJsonSchema.IUnknown;
+    namespace IJsonSchema {
+        /** Constant value type. */
+        interface IConstant extends IJsonSchemaAttribute {
+            /** Constant value. */
+            const: boolean | number | string;
+        }
+        /** Boolean type. */
+        interface IBoolean extends IJsonSchemaAttribute.IBoolean {
+            /** Default value. */
+            default?: boolean;
+        }
+        /** Integer type. */
+        interface IInteger extends IJsonSchemaAttribute.IInteger {
+            /** Default value. */
+            default?: number & tags.Type<"int64">;
+            /** Minimum value. */
+            minimum?: number & tags.Type<"int64">;
+            /** Maximum value. */
+            maximum?: number & tags.Type<"int64">;
+            /** Exclusive minimum. */
+            exclusiveMinimum?: number & tags.Type<"int64">;
+            /** Exclusive maximum. */
+            exclusiveMaximum?: number & tags.Type<"int64">;
+            /** Multiple of constraint. */
+            multipleOf?: number & tags.ExclusiveMinimum<0>;
+        }
+        /** Number (double) type. */
+        interface INumber extends IJsonSchemaAttribute.INumber {
+            /** Default value. */
+            default?: number;
+            /** Minimum value. */
+            minimum?: number;
+            /** Maximum value. */
+            maximum?: number;
+            /** Exclusive minimum. */
+            exclusiveMinimum?: number;
+            /** Exclusive maximum. */
+            exclusiveMaximum?: number;
+            /** Multiple of constraint. */
+            multipleOf?: number & tags.ExclusiveMinimum<0>;
+        }
+        /** String type. */
+        interface IString extends IJsonSchemaAttribute.IString {
+            /** Default value. */
+            default?: string;
+            /** String format. */
+            format?: "binary" | "byte" | "password" | "regex" | "uuid" | "email" | "hostname" | "idn-email" | "idn-hostname" | "iri" | "iri-reference" | "ipv4" | "ipv6" | "uri" | "uri-reference" | "uri-template" | "url" | "date-time" | "date" | "time" | "duration" | "json-pointer" | "relative-json-pointer" | (string & {});
+            /** Regex pattern. */
+            pattern?: string;
+            /** Content media type. */
+            contentMediaType?: string;
+            /** Minimum length. */
+            minLength?: number & tags.Type<"uint64">;
+            /** Maximum length. */
+            maxLength?: number & tags.Type<"uint64">;
+        }
+        /** Array type. */
+        interface IArray extends IJsonSchemaAttribute.IArray {
+            /** Element type. */
+            items: IJsonSchema;
+            /** Whether elements must be unique. */
+            uniqueItems?: boolean;
+            /** Minimum items. */
+            minItems?: number & tags.Type<"uint64">;
+            /** Maximum items. */
+            maxItems?: number & tags.Type<"uint64">;
+        }
+        /** Tuple type. */
+        interface ITuple extends IJsonSchemaAttribute {
+            /** Type discriminator. */
+            type: "array";
+            /** Tuple element types. */
+            prefixItems: IJsonSchema[];
+            /** Rest element type or `true` for any. */
+            additionalItems?: boolean | IJsonSchema;
+            /** Whether elements must be unique. */
+            uniqueItems?: boolean;
+            /** Minimum items. */
+            minItems?: number & tags.Type<"uint64">;
+            /** Maximum items. */
+            maxItems?: number & tags.Type<"uint64">;
+        }
+        /** Object type. */
+        interface IObject extends IJsonSchemaAttribute.IObject {
+            /** Property schemas. */
+            properties?: Record<string, IJsonSchema>;
+            /** Additional properties schema or `true` for any. */
+            additionalProperties?: boolean | IJsonSchema;
+            /** Required property names. */
+            required?: string[];
+        }
+        /** Reference to named schema. */
+        interface IReference<Key = string> extends IJsonSchemaAttribute {
+            /** Reference path (e.g., `#/components/schemas/TypeName`). */
+            $ref: Key;
+        }
+        /** Union type (`oneOf`). */
+        interface IOneOf extends IJsonSchemaAttribute {
+            /** Union member schemas. */
+            oneOf: Exclude<IJsonSchema, IJsonSchema.IOneOf>[];
+            /** Discriminator for tagged unions. */
+            discriminator?: IOneOf.IDiscriminator;
+        }
+        namespace IOneOf {
+            /** Discriminator for tagged unions. */
+            interface IDiscriminator {
+                /** Discriminator property name. */
+                propertyName: string;
+                /** Value to schema mapping. */
+                mapping?: Record<string, string>;
+            }
+        }
+        /** Null type. */
+        interface INull extends IJsonSchemaAttribute.INull {
+            /** Default value. */
+            default?: null;
+        }
+        /** Unknown (`any`) type. */
+        interface IUnknown extends IJsonSchemaAttribute.IUnknown {
+            /** Default value. */
+            default?: any;
+        }
+    }
+    /** Security scheme types. */
+    type ISecurityScheme = ISecurityScheme.IApiKey | ISecurityScheme.IHttpBasic | ISecurityScheme.IHttpBearer | ISecurityScheme.IOAuth2 | ISecurityScheme.IOpenId;
+    namespace ISecurityScheme {
+        /** API key authentication. */
+        interface IApiKey {
+            /** Scheme type. */
+            type: "apiKey";
+            /** Key location. */
+            in?: "header" | "query" | "cookie";
+            /** Key name. */
+            name?: string;
+            /** Scheme description. */
+            description?: string;
+        }
+        /** HTTP basic authentication. */
+        interface IHttpBasic {
+            /** Scheme type. */
+            type: "http";
+            /** Authentication scheme. */
+            scheme: "basic";
+            /** Scheme description. */
+            description?: string;
+        }
+        /** HTTP bearer authentication. */
+        interface IHttpBearer {
+            /** Scheme type. */
+            type: "http";
+            /** Authentication scheme. */
+            scheme: "bearer";
+            /** Bearer token format hint. */
+            bearerFormat?: string;
+            /** Scheme description. */
+            description?: string;
+        }
+        /** OAuth2 authentication. */
+        interface IOAuth2 {
+            /** Scheme type. */
+            type: "oauth2";
+            /** OAuth2 flows. */
+            flows: IOAuth2.IFlowSet;
+            /** Scheme description. */
+            description?: string;
+        }
+        /** OpenID Connect authentication. */
+        interface IOpenId {
+            /** Scheme type. */
+            type: "openIdConnect";
+            /** OpenID Connect discovery URL. */
+            openIdConnectUrl: string;
+            /** Scheme description. */
+            description?: string;
+        }
+        namespace IOAuth2 {
+            /** OAuth2 flow configurations. */
+            interface IFlowSet {
+                /** Authorization code flow. */
+                authorizationCode?: IFlow;
+                /** Implicit flow. */
+                implicit?: Omit<IFlow, "tokenUrl">;
+                /** Password flow. */
+                password?: Omit<IFlow, "authorizationUrl">;
+                /** Client credentials flow. */
+                clientCredentials?: Omit<IFlow, "authorizationUrl">;
+            }
+            /** OAuth2 flow configuration. */
+            interface IFlow {
+                /** Authorization URL. */
+                authorizationUrl?: string;
+                /** Token URL. */
+                tokenUrl?: string;
+                /** Refresh URL. */
+                refreshUrl?: string;
+                /** Available scopes. */
+                scopes?: Record<string, string>;
+            }
+        }
+    }
+}

package/lib/openapi/OpenApi.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=OpenApi.js.map

package/lib/openapi/OpenApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenApi.js","sourceRoot":"","sources":["../../src/openapi/OpenApi.ts"],"names":[],"mappings":""}