@beignet/core 0.0.1 → 0.0.2

package/src/openapi/index.ts

@@ -26,18 +26,36 @@ export {
 } from "./schema-introspector";
 
 /**
- * OpenAPI 3.1 Info Object
+ * OpenAPI 3.1 info object.
  */
 export interface OpenAPIInfo {
+  /**
+   * API title.
+   */
   title: string;
+  /**
+   * API version.
+   */
   version: string;
+  /**
+   * API description.
+   */
   description?: string;
+  /**
+   * Terms of service URL.
+   */
   termsOfService?: string;
+  /**
+   * API contact information.
+   */
   contact?: {
     name?: string;
     url?: string;
     email?: string;
   };
+  /**
+   * API license information.
+   */
   license?: {
     name: string;
     url?: string;
@@ -45,11 +63,20 @@ export interface OpenAPIInfo {
 }
 
 /**
- * OpenAPI 3.1 Server Object
+ * OpenAPI 3.1 server object.
  */
 export interface OpenAPIServer {
+  /**
+   * Server URL.
+   */
   url: string;
+  /**
+   * Server description.
+   */
   description?: string;
+  /**
+   * Server URL variables.
+   */
   variables?: Record<
     string,
     {
@@ -61,7 +88,7 @@ export interface OpenAPIServer {
 }
 
 /**
- * OpenAPI 3.1 Security Scheme Object
+ * OpenAPI 3.1 security scheme object.
  */
 export type OpenAPISecurityScheme =
   | {
@@ -88,29 +115,60 @@ export type OpenAPISecurityScheme =
     };
 
 /**
- * Schema or Reference object for OpenAPI
+ * OpenAPI schema object.
  */
 export type SchemaObject = Record<string, unknown>;
+
+/**
+ * OpenAPI reference object.
+ */
 export type ReferenceObject = { $ref: string };
 
 /**
- * OpenAPI Parameter Object
+ * OpenAPI parameter object.
  */
 export interface ParameterObject {
+  /**
+   * Parameter name.
+   */
   name: string;
+  /**
+   * Parameter location.
+   */
   in: "path" | "query" | "header" | "cookie";
+  /**
+   * Whether the parameter is required.
+   */
   required?: boolean;
+  /**
+   * Parameter schema.
+   */
   schema?: SchemaObject | ReferenceObject;
+  /**
+   * Parameter description.
+   */
   description?: string;
+  /**
+   * Whether the parameter is deprecated.
+   */
   deprecated?: boolean;
 }
 
 /**
- * OpenAPI Request Body Object
+ * OpenAPI request body object.
  */
 export interface RequestBodyObject {
+  /**
+   * Whether the request body is required.
+   */
   required?: boolean;
+  /**
+   * Request body description.
+   */
   description?: string;
+  /**
+   * Request body content keyed by media type.
+   */
   content: Record<
     string,
     {
@@ -120,10 +178,16 @@ export interface RequestBodyObject {
 }
 
 /**
- * OpenAPI Response Object
+ * OpenAPI response object.
  */
 export interface ResponseObject {
+  /**
+   * Response description.
+   */
   description: string;
+  /**
+   * Response content keyed by media type.
+   */
   content?: Record<
     string,
     {
@@ -140,26 +204,56 @@ export interface ResponseObject {
 }
 
 /**
- * OpenAPI Operation Object
+ * OpenAPI operation object.
  */
 export interface OperationObject {
+  /**
+   * Operation ID.
+   */
   operationId?: string;
+  /**
+   * Operation summary.
+   */
   summary?: string;
+  /**
+   * Operation description.
+   */
   description?: string;
+  /**
+   * Operation tags.
+   */
   tags?: string[];
+  /**
+   * Whether the operation is deprecated.
+   */
   deprecated?: boolean;
+  /**
+   * External documentation.
+   */
   externalDocs?: {
     description?: string;
     url: string;
   };
+  /**
+   * Operation-specific security requirements.
+   */
   security?: Array<Record<string, string[]>>;
+  /**
+   * Operation parameters.
+   */
   parameters?: ParameterObject[];
+  /**
+   * Operation request body.
+   */
   requestBody?: RequestBodyObject;
+  /**
+   * Operation responses keyed by status code.
+   */
   responses: Record<string, ResponseObject>;
 }
 
 /**
- * OpenAPI Path Item Object
+ * OpenAPI path item object.
  */
 export interface PathItemObject {
   get?: OperationObject;
@@ -172,32 +266,56 @@ export interface PathItemObject {
 }
 
 /**
- * OpenAPI Paths Object
+ * OpenAPI paths object.
  */
 export type PathsObject = Record<string, PathItemObject>;
 
 /**
- * OpenAPI Components Object
+ * OpenAPI components object.
  */
 export interface ComponentsObject {
+  /**
+   * Reusable schemas keyed by component name.
+   */
   schemas?: Record<string, SchemaObject>;
+  /**
+   * Reusable security schemes keyed by scheme name.
+   */
   securitySchemes?: Record<string, OpenAPISecurityScheme>;
 }
 
 /**
- * OpenAPI 3.1 Document
+ * OpenAPI 3.1 document.
  */
 export interface OpenAPIObject {
+  /**
+   * OpenAPI version.
+   */
   openapi: "3.1.0";
+  /**
+   * API info.
+   */
   info: OpenAPIInfo;
+  /**
+   * Server list.
+   */
   servers?: OpenAPIServer[];
+  /**
+   * API paths.
+   */
   paths: PathsObject;
+  /**
+   * Reusable components.
+   */
   components?: ComponentsObject;
+  /**
+   * Global security requirements.
+   */
   security?: Array<Record<string, string[]>>;
 }
 
 /**
- * Options for generating OpenAPI spec
+ * Options for generating an OpenAPI document.
  */
 export interface OpenAPIGeneratorOptions {
   /** API title */
@@ -234,13 +352,12 @@ type GeneratorState = {
 type SchemaIO = "input" | "output";
 
 /**
- * Type for contracts that can be passed to the generator.
- * Accepts both ContractBuilder instances and plain HttpContractConfig objects.
+ * Contract input accepted by the OpenAPI generator.
  */
 export type ContractInput = ContractLike;
 
 /**
- * Convert an array of contracts to an OpenAPI 3.1 document
+ * Convert contracts to an OpenAPI 3.1 document.
  *
  * @param contracts - Array of HTTP contracts (ContractBuilder instances or configs)
  * @param options - OpenAPI generation options