smartserve/ts/openapi/openapi.types.ts

/**
 * OpenAPI 3.1 Specification Types
 * Based on https://spec.openapis.org/oas/v3.1.0
 */

import type { TJsonSchema } from '../decorators/decorators.types.js';

// =============================================================================
// OpenAPI Specification Root
// =============================================================================

/**
 * OpenAPI 3.1 Specification
 */
export interface IOpenApiSpec {
  /** OpenAPI specification version */
  openapi: '3.1.0';
  /** API metadata */
  info: IOpenApiInfo;
  /** JSON Schema dialect (OpenAPI 3.1 default) */
  jsonSchemaDialect?: string;
  /** Server information */
  servers?: IOpenApiServer[];
  /** Available paths and operations */
  paths: Record<string, IOpenApiPathItem>;
  /** Webhooks */
  webhooks?: Record<string, IOpenApiPathItem>;
  /** Reusable components */
  components?: IOpenApiComponents;
  /** Security requirements */
  security?: IOpenApiSecurityRequirement[];
  /** Tags for organization */
  tags?: IOpenApiTag[];
  /** External documentation */
  externalDocs?: IOpenApiExternalDocs;
}

// =============================================================================
// Info Object
// =============================================================================

/**
 * API metadata
 */
export interface IOpenApiInfo {
  /** API title */
  title: string;
  /** API version */
  version: string;
  /** API description (markdown supported) */
  description?: string;
  /** Terms of service URL */
  termsOfService?: string;
  /** Contact information */
  contact?: IOpenApiContact;
  /** License information */
  license?: IOpenApiLicense;
  /** Short summary */
  summary?: string;
}

/**
 * Contact information
 */
export interface IOpenApiContact {
  name?: string;
  url?: string;
  email?: string;
}

/**
 * License information
 */
export interface IOpenApiLicense {
  name: string;
  url?: string;
  identifier?: string;
}

// =============================================================================
// Server Object
// =============================================================================

/**
 * Server information
 */
export interface IOpenApiServer {
  /** Server URL */
  url: string;
  /** Server description */
  description?: string;
  /** Server variables */
  variables?: Record<string, IOpenApiServerVariable>;
}

/**
 * Server variable
 */
export interface IOpenApiServerVariable {
  default: string;
  description?: string;
  enum?: string[];
}

// =============================================================================
// Path & Operation Objects
// =============================================================================

/**
 * Path item with operations
 */
export interface IOpenApiPathItem {
  /** Reference to another path item */
  $ref?: string;
  /** Summary */
  summary?: string;
  /** Description */
  description?: string;
  /** GET operation */
  get?: IOpenApiOperation;
  /** PUT operation */
  put?: IOpenApiOperation;
  /** POST operation */
  post?: IOpenApiOperation;
  /** DELETE operation */
  delete?: IOpenApiOperation;
  /** OPTIONS operation */
  options?: IOpenApiOperation;
  /** HEAD operation */
  head?: IOpenApiOperation;
  /** PATCH operation */
  patch?: IOpenApiOperation;
  /** TRACE operation */
  trace?: IOpenApiOperation;
  /** Servers for this path */
  servers?: IOpenApiServer[];
  /** Parameters for all operations */
  parameters?: IOpenApiParameter[];
}

/**
 * API operation
 */
export interface IOpenApiOperation {
  /** Tags for grouping */
  tags?: string[];
  /** Short summary */
  summary?: string;
  /** Detailed description */
  description?: string;
  /** External documentation */
  externalDocs?: IOpenApiExternalDocs;
  /** Unique operation ID */
  operationId?: string;
  /** Operation parameters */
  parameters?: IOpenApiParameter[];
  /** Request body */
  requestBody?: IOpenApiRequestBody;
  /** Responses */
  responses: Record<string, IOpenApiResponse>;
  /** Callbacks */
  callbacks?: Record<string, Record<string, IOpenApiPathItem>>;
  /** Deprecation flag */
  deprecated?: boolean;
  /** Security requirements */
  security?: IOpenApiSecurityRequirement[];
  /** Servers for this operation */
  servers?: IOpenApiServer[];
}

// =============================================================================
// Parameter Object
// =============================================================================

/**
 * Operation parameter
 */
export interface IOpenApiParameter {
  /** Parameter name */
  name: string;
  /** Parameter location */
  in: 'query' | 'header' | 'path' | 'cookie';
  /** Description */
  description?: string;
  /** Required flag (path params always required) */
  required?: boolean;
  /** Deprecation flag */
  deprecated?: boolean;
  /** Allow empty value */
  allowEmptyValue?: boolean;
  /** Parameter schema */
  schema?: TJsonSchema;
  /** Example value */
  example?: unknown;
  /** Multiple examples */
  examples?: Record<string, IOpenApiExample>;
  /** Serialization style */
  style?: 'matrix' | 'label' | 'form' | 'simple' | 'spaceDelimited' | 'pipeDelimited' | 'deepObject';
  /** Explode arrays/objects */
  explode?: boolean;
  /** Allow reserved characters */
  allowReserved?: boolean;
  /** Content type mapping */
  content?: Record<string, IOpenApiMediaType>;
}

// =============================================================================
// Request Body Object
// =============================================================================

/**
 * Request body
 */
export interface IOpenApiRequestBody {
  /** Description */
  description?: string;
  /** Content by media type */
  content: Record<string, IOpenApiMediaType>;
  /** Required flag */
  required?: boolean;
}

// =============================================================================
// Media Type Object
// =============================================================================

/**
 * Media type content
 */
export interface IOpenApiMediaType {
  /** Content schema */
  schema?: TJsonSchema;
  /** Example value */
  example?: unknown;
  /** Multiple examples */
  examples?: Record<string, IOpenApiExample>;
  /** Encoding for multipart */
  encoding?: Record<string, IOpenApiEncoding>;
}

/**
 * Encoding for multipart content
 */
export interface IOpenApiEncoding {
  contentType?: string;
  headers?: Record<string, IOpenApiParameter>;
  style?: string;
  explode?: boolean;
  allowReserved?: boolean;
}

// =============================================================================
// Response Object
// =============================================================================

/**
 * Operation response
 */
export interface IOpenApiResponse {
  /** Response description (required) */
  description: string;
  /** Response headers */
  headers?: Record<string, IOpenApiParameter>;
  /** Response content */
  content?: Record<string, IOpenApiMediaType>;
  /** Links */
  links?: Record<string, IOpenApiLink>;
}

/**
 * Response link
 */
export interface IOpenApiLink {
  operationRef?: string;
  operationId?: string;
  parameters?: Record<string, unknown>;
  requestBody?: unknown;
  description?: string;
  server?: IOpenApiServer;
}

// =============================================================================
// Example Object
// =============================================================================

/**
 * Example value
 */
export interface IOpenApiExample {
  /** Short summary */
  summary?: string;
  /** Description */
  description?: string;
  /** Example value */
  value?: unknown;
  /** External URL */
  externalValue?: string;
}

// =============================================================================
// Components Object
// =============================================================================

/**
 * Reusable components
 */
export interface IOpenApiComponents {
  /** Reusable schemas */
  schemas?: Record<string, TJsonSchema>;
  /** Reusable responses */
  responses?: Record<string, IOpenApiResponse>;
  /** Reusable parameters */
  parameters?: Record<string, IOpenApiParameter>;
  /** Reusable examples */
  examples?: Record<string, IOpenApiExample>;
  /** Reusable request bodies */
  requestBodies?: Record<string, IOpenApiRequestBody>;
  /** Reusable headers */
  headers?: Record<string, IOpenApiParameter>;
  /** Security schemes */
  securitySchemes?: Record<string, IOpenApiSecurityScheme>;
  /** Reusable links */
  links?: Record<string, IOpenApiLink>;
  /** Reusable callbacks */
  callbacks?: Record<string, Record<string, IOpenApiPathItem>>;
  /** Path items */
  pathItems?: Record<string, IOpenApiPathItem>;
}

// =============================================================================
// Security Scheme Object
// =============================================================================

/**
 * Security scheme definition
 */
export type IOpenApiSecurityScheme =
  | IOpenApiSecuritySchemeApiKey
  | IOpenApiSecuritySchemeHttp
  | IOpenApiSecuritySchemeOAuth2
  | IOpenApiSecuritySchemeOpenIdConnect
  | IOpenApiSecuritySchemeMutualTLS;

/**
 * API key security scheme
 */
export interface IOpenApiSecuritySchemeApiKey {
  type: 'apiKey';
  description?: string;
  name: string;
  in: 'query' | 'header' | 'cookie';
}

/**
 * HTTP security scheme (bearer, basic, etc.)
 */
export interface IOpenApiSecuritySchemeHttp {
  type: 'http';
  description?: string;
  scheme: string;
  bearerFormat?: string;
}

/**
 * OAuth2 security scheme
 */
export interface IOpenApiSecuritySchemeOAuth2 {
  type: 'oauth2';
  description?: string;
  flows: IOpenApiOAuthFlows;
}

/**
 * OpenID Connect security scheme
 */
export interface IOpenApiSecuritySchemeOpenIdConnect {
  type: 'openIdConnect';
  description?: string;
  openIdConnectUrl: string;
}

/**
 * Mutual TLS security scheme
 */
export interface IOpenApiSecuritySchemeMutualTLS {
  type: 'mutualTLS';
  description?: string;
}

/**
 * OAuth2 flows
 */
export interface IOpenApiOAuthFlows {
  implicit?: IOpenApiOAuthFlow;
  password?: IOpenApiOAuthFlow;
  clientCredentials?: IOpenApiOAuthFlow;
  authorizationCode?: IOpenApiOAuthFlow;
}

/**
 * OAuth2 flow
 */
export interface IOpenApiOAuthFlow {
  authorizationUrl?: string;
  tokenUrl?: string;
  refreshUrl?: string;
  scopes: Record<string, string>;
}

/**
 * Security requirement
 */
export type IOpenApiSecurityRequirement = Record<string, string[]>;

// =============================================================================
// Tag & External Docs Objects
// =============================================================================

/**
 * Tag for grouping operations
 */
export interface IOpenApiTag {
  /** Tag name */
  name: string;
  /** Tag description */
  description?: string;
  /** External documentation */
  externalDocs?: IOpenApiExternalDocs;
}

/**
 * External documentation
 */
export interface IOpenApiExternalDocs {
  /** Documentation URL */
  url: string;
  /** Description */
  description?: string;
}

// =============================================================================
// Generator Options
// =============================================================================

/**
 * Options for OpenAPI spec generation
 */
export interface IOpenApiGeneratorOptions {
  /** API info (required) */
  info: IOpenApiInfo;
  /** Server URLs */
  servers?: IOpenApiServer[];
  /** Security scheme definitions */
  securitySchemes?: Record<string, IOpenApiSecurityScheme>;
  /** Global tags */
  tags?: IOpenApiTag[];
  /** External documentation */
  externalDocs?: IOpenApiExternalDocs;
}

/**
 * Options for OpenAPI in SmartServe
 */
export interface IOpenApiOptions {
  /** Enable OpenAPI (default: true when options provided) */
  enabled?: boolean;
  /** Path for OpenAPI JSON spec (default: /openapi.json) */
  specPath?: string;
  /** Path for Swagger UI (default: /docs) */
  docsPath?: string;
  /** Enable runtime validation (default: true) */
  validation?: boolean;
  /** API info */
  info: {
    title: string;
    version: string;
    description?: string;
    termsOfService?: string;
    contact?: IOpenApiContact;
    license?: IOpenApiLicense;
  };
  /** Server URLs */
  servers?: IOpenApiServer[];
  /** Security schemes */
  securitySchemes?: Record<string, IOpenApiSecurityScheme>;
  /** Global tags */
  tags?: IOpenApiTag[];
}