@skmtc/core 0.0.791 → 0.0.792

package/esm/oas/header/Header.js

@@ -10,7 +10,213 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _OasHeader_fields;
-/** Describes a single header in the API */
+/**
+ * Represents a Header Object in the OpenAPI Specification.
+ *
+ * The `OasHeader` class encapsulates the definition of a single HTTP header that
+ * can be sent with responses or expected in requests. Headers provide additional
+ * metadata about the HTTP message and can include authentication tokens, content
+ * information, pagination data, rate limiting details, and more.
+ *
+ * This class provides comprehensive support for header definitions with typed
+ * values, validation schemas, examples, and documentation.
+ *
+ * ## Key Features
+ *
+ * - **Schema Validation**: Typed header values through schema definitions
+ * - **Examples**: Multiple example values for documentation and testing
+ * - **Content Types**: Support for complex header values with media types
+ * - **Deprecation Support**: Mark headers as deprecated with proper warnings
+ * - **Required/Optional**: Control whether headers are mandatory
+ * - **Documentation**: Rich description support for API documentation
+ *
+ * @example Basic authentication header
+ * ```typescript
+ * import { OasHeader, OasString } from '@skmtc/core';
+ *
+ * const authHeader = new OasHeader({
+ *   description: 'Bearer token for API authentication',
+ *   required: true,
+ *   schema: new OasString({
+ *     pattern: '^Bearer [A-Za-z0-9+/=]+$',
+ *     description: 'JWT bearer token'
+ *   }),
+ *   examples: {
+ *     valid: new OasExample({
+ *       summary: 'Valid bearer token',
+ *       value: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Pagination headers
+ * ```typescript
+ * const totalCountHeader = new OasHeader({
+ *   description: 'Total number of items available',
+ *   required: false,
+ *   schema: new OasInteger({
+ *     minimum: 0,
+ *     description: 'Non-negative integer count'
+ *   }),
+ *   examples: {
+ *     empty: new OasExample({ value: 0, description: 'No items' }),
+ *     normal: new OasExample({ value: 150, description: 'Normal case' }),
+ *     large: new OasExample({ value: 10000, description: 'Large dataset' })
+ *   }
+ * });
+ *
+ * const linkHeader = new OasHeader({
+ *   description: 'Pagination links (RFC 5988)',
+ *   required: false,
+ *   schema: new OasString({
+ *     description: 'Comma-separated list of link relations'
+ *   }),
+ *   examples: {
+ *     withNext: new OasExample({
+ *       value: '</api/users?page=2>; rel="next", </api/users?page=10>; rel="last"'
+ *     }),
+ *     lastPage: new OasExample({
+ *       value: '</api/users?page=9>; rel="prev", </api/users?page=1>; rel="first"'
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Content type and encoding headers
+ * ```typescript
+ * const contentTypeHeader = new OasHeader({
+ *   description: 'MIME type of the response content',
+ *   required: true,
+ *   schema: new OasString({
+ *     enum: [
+ *       'application/json',
+ *       'application/xml',
+ *       'text/csv',
+ *       'application/pdf',
+ *       'application/octet-stream'
+ *     ]
+ *   }),
+ *   examples: {
+ *     json: new OasExample({ value: 'application/json' }),
+ *     xml: new OasExample({ value: 'application/xml' }),
+ *     csv: new OasExample({ value: 'text/csv' })
+ *   }
+ * });
+ *
+ * const contentLengthHeader = new OasHeader({
+ *   description: 'Size of the response body in bytes',
+ *   required: false,
+ *   schema: new OasInteger({
+ *     minimum: 0,
+ *     description: 'Content size in bytes'
+ *   })
+ * });
+ * ```
+ *
+ * @example Rate limiting headers
+ * ```typescript
+ * const rateLimitHeader = new OasHeader({
+ *   description: 'Number of requests remaining in the current window',
+ *   required: false,
+ *   schema: new OasInteger({
+ *     minimum: 0,
+ *     description: 'Remaining request count'
+ *   }),
+ *   examples: {
+ *     available: new OasExample({ value: 95, description: '95 requests remaining' }),
+ *     depleted: new OasExample({ value: 0, description: 'Rate limit reached' })
+ *   }
+ * });
+ *
+ * const rateLimitResetHeader = new OasHeader({
+ *   description: 'Unix timestamp when the rate limit window resets',
+ *   required: false,
+ *   schema: new OasInteger({
+ *     minimum: 0,
+ *     description: 'Unix timestamp in seconds'
+ *   }),
+ *   examples: {
+ *     reset: new OasExample({
+ *       value: 1634567890,
+ *       description: 'Reset at 2021-10-18 12:31:30 UTC'
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Custom application headers
+ * ```typescript
+ * const requestIdHeader = new OasHeader({
+ *   description: 'Unique identifier for request tracing',
+ *   required: false,
+ *   schema: new OasString({
+ *     format: 'uuid',
+ *     description: 'UUID v4 request identifier'
+ *   }),
+ *   examples: {
+ *     uuid: new OasExample({
+ *       value: '123e4567-e89b-12d3-a456-426614174000',
+ *       description: 'Request tracking ID'
+ *     })
+ *   }
+ * });
+ *
+ * const serverTimingHeader = new OasHeader({
+ *   description: 'Server-side performance metrics',
+ *   required: false,
+ *   schema: new OasString({
+ *     description: 'Server-Timing header format (RFC 8760)'
+ *   }),
+ *   examples: {
+ *     timing: new OasExample({
+ *       value: 'db;dur=53, app;dur=47.2',
+ *       description: 'Database took 53ms, app logic 47.2ms'
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Deprecated header
+ * ```typescript
+ * const deprecatedHeader = new OasHeader({
+ *   description: 'Legacy API version header (deprecated)',
+ *   required: false,
+ *   deprecated: true,
+ *   schema: new OasString({
+ *     enum: ['v1', 'v2'],
+ *     description: 'Use Accept or Content-Type header instead'
+ *   }),
+ *   examples: {
+ *     legacy: new OasExample({
+ *       value: 'v1',
+ *       description: 'Legacy version (use Accept header instead)'
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example Using in response definitions
+ * ```typescript
+ * const successResponse = new OasResponse({
+ *   description: 'Paginated user list',
+ *   headers: {
+ *     'X-Total-Count': totalCountHeader,
+ *     'Link': linkHeader,
+ *     'X-Rate-Limit-Remaining': rateLimitHeader,
+ *     'X-Rate-Limit-Reset': rateLimitResetHeader,
+ *     'X-Request-ID': requestIdHeader
+ *   },
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasArray({
+ *         items: new OasRef({ $ref: '#/components/schemas/User' })
+ *       })
+ *     })
+ *   }
+ * });
+ * ```
+ */
 export class OasHeader {
     constructor(fields) {
         Object.defineProperty(this, "oasType", {

package/esm/oas/info/Info.d.ts

@@ -1,15 +1,87 @@
 import "../../_dnt.polyfills.js";
 import type { OasContact } from '../contact/Contact.js';
 import type { OasLicense } from '../license/License.js';
+/**
+ * Constructor fields for {@link OasInfo}.
+ */
 export type InfoFields = {
+    /** The title of the API */
     title: string;
+    /** The version of the OpenAPI document */
     version: string;
+    /** A description of the API */
     description?: string | undefined;
+    /** A URL to the Terms of Service for the API */
     termsOfService?: string | undefined;
+    /** The contact information for the exposed API */
     contact?: OasContact | undefined;
+    /** The license information for the exposed API */
     license?: OasLicense | undefined;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
 };
+/**
+ * Represents an Info Object in the OpenAPI Specification.
+ *
+ * The `OasInfo` class encapsulates metadata about the API including its title,
+ * version, description, and contact information. This information is displayed
+ * in API documentation and helps developers understand what the API does and
+ * how to use it effectively.
+ *
+ * This class provides essential API metadata that appears at the top level
+ * of OpenAPI documents and drives documentation generation and tooling.
+ *
+ * ## Key Features
+ *
+ * - **API Identification**: Title and version information for API tracking
+ * - **Documentation**: Rich description support for API overview
+ * - **Contact Information**: Developer contact details and support resources
+ * - **Legal Information**: License and terms of service references
+ * - **Extension Support**: Custom fields for additional metadata
+ *
+ * @example Basic API information
+ * ```typescript
+ * import { OasInfo } from '@skmtc/core';
+ *
+ * const apiInfo = new OasInfo({
+ *   title: 'Pet Store API',
+ *   version: '1.0.0',
+ *   description: 'A sample API that uses a petstore as an example'
+ * });
+ * ```
+ *
+ * @example Complete API metadata
+ * ```typescript
+ * const fullApiInfo = new OasInfo({
+ *   title: 'E-Commerce Platform API',
+ *   version: '2.1.0',
+ *   description: 'Comprehensive e-commerce API for managing products, orders, and customers',
+ *   termsOfService: 'https://api.example.com/terms',
+ *   contact: new OasContact({
+ *     name: 'API Support Team',
+ *     url: 'https://api.example.com/support',
+ *     email: 'api-support@example.com'
+ *   }),
+ *   license: new OasLicense({
+ *     name: 'MIT',
+ *     url: 'https://opensource.org/licenses/MIT'
+ *   })
+ * });
+ * ```
+ *
+ * @example Versioned API with semantic versioning
+ * ```typescript
+ * const versionedInfo = new OasInfo({
+ *   title: 'User Management Service',
+ *   version: '3.2.1',
+ *   description: 'RESTful API for user authentication and profile management',
+ *   contact: new OasContact({
+ *     name: 'Development Team',
+ *     email: 'dev@company.com'
+ *   })
+ * });
+ * ```
+ */
 export declare class OasInfo {
     #private;
     oasType: 'info';

package/esm/oas/info/Info.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Info.d.ts","sourceRoot":"","sources":["../../../src/oas/info/Info.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAEvD,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,OAAO,CAAC,EAAE,UAAU,GAAG,SAAS,CAAA;IAChC,OAAO,CAAC,EAAE,UAAU,GAAG,SAAS,CAAA;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,qBAAa,OAAO;;IAClB,OAAO,EAAE,MAAM,CAAS;gBAGZ,MAAM,EAAE,UAAU;IAI9B,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,IAAI,cAAc,IAAI,MAAM,GAAG,SAAS,CAEvC;IAED,IAAI,OAAO,IAAI,UAAU,GAAG,SAAS,CAEpC;IAED,IAAI,OAAO,IAAI,UAAU,GAAG,SAAS,CAEpC;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEzD;CACF"}
+{"version":3,"file":"Info.d.ts","sourceRoot":"","sources":["../../../src/oas/info/Info.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAEvD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,kDAAkD;IAClD,OAAO,CAAC,EAAE,UAAU,GAAG,SAAS,CAAA;IAChC,kDAAkD;IAClD,OAAO,CAAC,EAAE,UAAU,GAAG,SAAS,CAAA;IAChC,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,qBAAa,OAAO;;IAClB,OAAO,EAAE,MAAM,CAAS;gBAGZ,MAAM,EAAE,UAAU;IAI9B,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,IAAI,cAAc,IAAI,MAAM,GAAG,SAAS,CAEvC;IAED,IAAI,OAAO,IAAI,UAAU,GAAG,SAAS,CAEpC;IAED,IAAI,OAAO,IAAI,UAAU,GAAG,SAAS,CAEpC;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEzD;CACF"}

package/esm/oas/info/Info.js

@@ -11,6 +11,68 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _OasInfo_fields;
 import "../../_dnt.polyfills.js";
+/**
+ * Represents an Info Object in the OpenAPI Specification.
+ *
+ * The `OasInfo` class encapsulates metadata about the API including its title,
+ * version, description, and contact information. This information is displayed
+ * in API documentation and helps developers understand what the API does and
+ * how to use it effectively.
+ *
+ * This class provides essential API metadata that appears at the top level
+ * of OpenAPI documents and drives documentation generation and tooling.
+ *
+ * ## Key Features
+ *
+ * - **API Identification**: Title and version information for API tracking
+ * - **Documentation**: Rich description support for API overview
+ * - **Contact Information**: Developer contact details and support resources
+ * - **Legal Information**: License and terms of service references
+ * - **Extension Support**: Custom fields for additional metadata
+ *
+ * @example Basic API information
+ * ```typescript
+ * import { OasInfo } from '@skmtc/core';
+ *
+ * const apiInfo = new OasInfo({
+ *   title: 'Pet Store API',
+ *   version: '1.0.0',
+ *   description: 'A sample API that uses a petstore as an example'
+ * });
+ * ```
+ *
+ * @example Complete API metadata
+ * ```typescript
+ * const fullApiInfo = new OasInfo({
+ *   title: 'E-Commerce Platform API',
+ *   version: '2.1.0',
+ *   description: 'Comprehensive e-commerce API for managing products, orders, and customers',
+ *   termsOfService: 'https://api.example.com/terms',
+ *   contact: new OasContact({
+ *     name: 'API Support Team',
+ *     url: 'https://api.example.com/support',
+ *     email: 'api-support@example.com'
+ *   }),
+ *   license: new OasLicense({
+ *     name: 'MIT',
+ *     url: 'https://opensource.org/licenses/MIT'
+ *   })
+ * });
+ * ```
+ *
+ * @example Versioned API with semantic versioning
+ * ```typescript
+ * const versionedInfo = new OasInfo({
+ *   title: 'User Management Service',
+ *   version: '3.2.1',
+ *   description: 'RESTful API for user authentication and profile management',
+ *   contact: new OasContact({
+ *     name: 'Development Team',
+ *     email: 'dev@company.com'
+ *   })
+ * });
+ * ```
+ */
 export class OasInfo {
     constructor(fields) {
         Object.defineProperty(this, "oasType", {

package/esm/oas/mediaType/MediaType.d.ts

@@ -3,13 +3,98 @@ import type { OasSchema } from '../schema/Schema.js';
 import type { OasExample } from '../example/Example.js';
 import type { ToJsonSchemaOptions } from '../schema/Schema.js';
 import type { OpenAPIV3 } from 'openapi-types';
+/**
+ * Constructor fields for {@link OasMediaType}.
+ */
 export type MediaTypeFields = {
+    /** The media type string (e.g., 'application/json', 'text/xml') */
     mediaType: string;
+    /** The schema defining the structure of the content */
     schema?: OasSchema | OasRef<'schema'> | undefined;
+    /** Example values for the media type */
     examples?: Record<string, OasExample | OasRef<'example'>> | undefined;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
+    /** Encoding information for multipart or form data */
     encoding?: Record<string, unknown> | undefined;
 };
+/**
+ * Represents a Media Type Object in the OpenAPI Specification.
+ *
+ * The `OasMediaType` class encapsulates the definition of content for different
+ * media types in request bodies and responses. It defines the structure, format,
+ * and validation rules for content using schemas and provides examples for
+ * documentation and testing purposes.
+ *
+ * This class supports various content types including JSON, XML, form data,
+ * file uploads, and binary content, making it essential for describing API
+ * request and response payloads.
+ *
+ * ## Key Features
+ *
+ * - **Schema Validation**: Define content structure through OpenAPI schemas
+ * - **Multiple Examples**: Rich example support for documentation and testing
+ * - **Encoding Support**: Handle multipart and form data encoding
+ * - **Content Type Support**: JSON, XML, binary, form data, and more
+ * - **Reference Integration**: Work seamlessly with schema references
+ *
+ * @example JSON content type
+ * ```typescript
+ * import { OasMediaType, OasObject, OasString } from '@skmtc/core';
+ *
+ * const jsonContent = new OasMediaType({
+ *   mediaType: 'application/json',
+ *   schema: new OasObject({
+ *     properties: {
+ *       name: new OasString(),
+ *       email: new OasString({ format: 'email' })
+ *     }
+ *   }),
+ *   examples: {
+ *     user: new OasExample({
+ *       summary: 'Sample user',
+ *       value: { name: 'John Doe', email: 'john@example.com' }
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example File upload with multipart form data
+ * ```typescript
+ * const fileUpload = new OasMediaType({
+ *   mediaType: 'multipart/form-data',
+ *   schema: new OasObject({
+ *     properties: {
+ *       file: new OasString({ format: 'binary' }),
+ *       description: new OasString()
+ *     }
+ *   }),
+ *   encoding: {
+ *     file: {
+ *       contentType: 'image/png, image/jpeg',
+ *       style: 'form'
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example XML content with namespace
+ * ```typescript
+ * const xmlContent = new OasMediaType({
+ *   mediaType: 'application/xml',
+ *   schema: new OasObject({
+ *     properties: {
+ *       product: new OasRef({ $ref: '#/components/schemas/Product' })
+ *     }
+ *   }),
+ *   examples: {
+ *     sample: new OasExample({
+ *       value: '<product><name>Widget</name><price>19.99</price></product>'
+ *     })
+ *   }
+ * });
+ * ```
+ */
 export declare class OasMediaType {
     oasType: 'mediaType';
     mediaType: string;

package/esm/oas/mediaType/MediaType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MediaType.d.ts","sourceRoot":"","sources":["../../../src/oas/mediaType/MediaType.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;CAC/C,CAAA;AAED,qBAAa,YAAY;IACvB,OAAO,EAAE,WAAW,CAAc;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IAChD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACpE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;gBAClC,MAAM,EAAE,eAAe;IAQnC,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC,eAAe;CAMtE"}
+{"version":3,"file":"MediaType.d.ts","sourceRoot":"","sources":["../../../src/oas/mediaType/MediaType.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAA;IACjB,uDAAuD;IACvD,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACjD,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACrE,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzC,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;CAC/C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,qBAAa,YAAY;IACvB,OAAO,EAAE,WAAW,CAAc;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IAChD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACpE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;gBAClC,MAAM,EAAE,eAAe;IAQnC,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC,eAAe;CAMtE"}

package/esm/oas/mediaType/MediaType.js

@@ -1,3 +1,80 @@
+/**
+ * Represents a Media Type Object in the OpenAPI Specification.
+ *
+ * The `OasMediaType` class encapsulates the definition of content for different
+ * media types in request bodies and responses. It defines the structure, format,
+ * and validation rules for content using schemas and provides examples for
+ * documentation and testing purposes.
+ *
+ * This class supports various content types including JSON, XML, form data,
+ * file uploads, and binary content, making it essential for describing API
+ * request and response payloads.
+ *
+ * ## Key Features
+ *
+ * - **Schema Validation**: Define content structure through OpenAPI schemas
+ * - **Multiple Examples**: Rich example support for documentation and testing
+ * - **Encoding Support**: Handle multipart and form data encoding
+ * - **Content Type Support**: JSON, XML, binary, form data, and more
+ * - **Reference Integration**: Work seamlessly with schema references
+ *
+ * @example JSON content type
+ * ```typescript
+ * import { OasMediaType, OasObject, OasString } from '@skmtc/core';
+ *
+ * const jsonContent = new OasMediaType({
+ *   mediaType: 'application/json',
+ *   schema: new OasObject({
+ *     properties: {
+ *       name: new OasString(),
+ *       email: new OasString({ format: 'email' })
+ *     }
+ *   }),
+ *   examples: {
+ *     user: new OasExample({
+ *       summary: 'Sample user',
+ *       value: { name: 'John Doe', email: 'john@example.com' }
+ *     })
+ *   }
+ * });
+ * ```
+ *
+ * @example File upload with multipart form data
+ * ```typescript
+ * const fileUpload = new OasMediaType({
+ *   mediaType: 'multipart/form-data',
+ *   schema: new OasObject({
+ *     properties: {
+ *       file: new OasString({ format: 'binary' }),
+ *       description: new OasString()
+ *     }
+ *   }),
+ *   encoding: {
+ *     file: {
+ *       contentType: 'image/png, image/jpeg',
+ *       style: 'form'
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example XML content with namespace
+ * ```typescript
+ * const xmlContent = new OasMediaType({
+ *   mediaType: 'application/xml',
+ *   schema: new OasObject({
+ *     properties: {
+ *       product: new OasRef({ $ref: '#/components/schemas/Product' })
+ *     }
+ *   }),
+ *   examples: {
+ *     sample: new OasExample({
+ *       value: '<product><name>Widget</name><price>19.99</price></product>'
+ *     })
+ *   }
+ * });
+ * ```
+ */
 export class OasMediaType {
     constructor(fields) {
         Object.defineProperty(this, "oasType", {

package/esm/oas/pathItem/PathItem.d.ts

@@ -1,11 +1,103 @@
 import type { OasParameter } from '../parameter/Parameter.js';
 import type { OasRef } from '../ref/Ref.js';
+/**
+ * Constructor fields for {@link OasPathItem}.
+ */
 export type PathItemFields = {
+    /** Optional summary for the path item */
     summary?: string | undefined;
+    /** Optional description for the path item */
     description?: string | undefined;
+    /** Parameters that are applicable for all operations on this path */
     parameters?: (OasParameter | OasRef<'parameter'>)[] | undefined;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
 };
+/**
+ * Represents a Path Item Object in the OpenAPI Specification.
+ *
+ * The `OasPathItem` class describes operations available on a single API path.
+ * It serves as a container for HTTP operations (GET, POST, PUT, DELETE, etc.)
+ * and can define parameters that apply to all operations on the path.
+ *
+ * This class provides path-level configuration and shared parameters that
+ * reduce duplication across operations on the same endpoint.
+ *
+ * ## Key Features
+ *
+ * - **Operation Container**: Groups HTTP methods for a single path
+ * - **Shared Parameters**: Path-level parameters for all operations
+ * - **Documentation**: Summary and description for the path
+ * - **Extension Support**: Custom fields for additional metadata
+ * - **Parameter Inheritance**: Parameters shared across all operations
+ *
+ * @example Basic path item with shared parameters
+ * ```typescript
+ * import { OasPathItem, OasParameter, OasString } from '@skmtc/core';
+ *
+ * const userPathItem = new OasPathItem({
+ *   summary: 'User operations',
+ *   description: 'Operations for managing individual users',
+ *   parameters: [
+ *     new OasParameter({
+ *       name: 'userId',
+ *       in: 'path',
+ *       required: true,
+ *       schema: new OasString({ format: 'uuid' }),
+ *       description: 'Unique identifier for the user'
+ *     })
+ *   ]
+ * });
+ * ```
+ *
+ * @example Path with common headers
+ * ```typescript
+ * const apiPathItem = new OasPathItem({
+ *   summary: 'API endpoint',
+ *   description: 'Authenticated endpoint requiring API key',
+ *   parameters: [
+ *     new OasParameter({
+ *       name: 'Authorization',
+ *       in: 'header',
+ *       required: true,
+ *       schema: new OasString({ pattern: '^Bearer .+$' }),
+ *       description: 'Bearer token for authentication'
+ *     }),
+ *     new OasParameter({
+ *       name: 'Accept-Version',
+ *       in: 'header',
+ *       required: false,
+ *       schema: new OasString({ enum: ['v1', 'v2'] }),
+ *       description: 'API version preference'
+ *     })
+ *   ]
+ * });
+ * ```
+ *
+ * @example RESTful resource path
+ * ```typescript
+ * const resourcePathItem = new OasPathItem({
+ *   summary: 'Product resource',
+ *   description: 'CRUD operations for product management',
+ *   parameters: [
+ *     new OasParameter({
+ *       name: 'productId',
+ *       in: 'path',
+ *       required: true,
+ *       schema: new OasInteger({ minimum: 1 }),
+ *       description: 'Product identifier'
+ *     }),
+ *     new OasParameter({
+ *       name: 'include',
+ *       in: 'query',
+ *       required: false,
+ *       schema: new OasString({ enum: ['details', 'reviews', 'images'] }),
+ *       description: 'Additional data to include in response'
+ *     })
+ *   ]
+ * });
+ * ```
+ */
 export declare class OasPathItem {
     oasType: 'pathItem';
     summary: string | undefined;

package/esm/oas/pathItem/PathItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PathItem.d.ts","sourceRoot":"","sources":["../../../src/oas/pathItem/PathItem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAE3C,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,UAAU,CAAC,EAAE,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,GAAG,SAAS,CAAA;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,qBAAa,WAAW;IACtB,OAAO,EAAE,UAAU,CAAa;IAChC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,UAAU,EAAE,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,GAAG,SAAS,CAAA;IAC9D,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;gBAExC,MAAM,GAAE,cAAmB;CAMxC"}
+{"version":3,"file":"PathItem.d.ts","sourceRoot":"","sources":["../../../src/oas/pathItem/PathItem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAE3C;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,qEAAqE;IACrE,UAAU,CAAC,EAAE,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,GAAG,SAAS,CAAA;IAC/D,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AACH,qBAAa,WAAW;IACtB,OAAO,EAAE,UAAU,CAAa;IAChC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,UAAU,EAAE,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,EAAE,GAAG,SAAS,CAAA;IAC9D,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;gBAExC,MAAM,GAAE,cAAmB;CAMxC"}