feat(openapi): Add OpenAPI module: decorators, spec generator, runtime validation and Swagger UI
This commit is contained in:
488
ts/openapi/openapi.types.ts
Normal file
488
ts/openapi/openapi.types.ts
Normal file
@@ -0,0 +1,488 @@
|
||||
/**
|
||||
* 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[];
|
||||
}
|
||||
Reference in New Issue
Block a user