@tsed/schema
Version:
JsonSchema module for Ts.ED Framework
106 lines (105 loc) • 4.13 kB
TypeScript
import { OpenSpecSecurity, OpenSpecTag, OS3Operation } from "@tsed/openspec";
import { JsonHeader } from "../interfaces/JsonOpenSpec.js";
import { JsonMap } from "./JsonMap.js";
import { JsonParameter } from "./JsonParameter.js";
import { JsonResponse } from "./JsonResponse.js";
import { JsonSchema } from "./JsonSchema.js";
/**
* Represents an HTTP operation path with metadata for OpenAPI specifications.
*
* This class associates an HTTP method and path with operation-level metadata
* such as summary and description. It's used internally to manage routing
* information for API endpoints.
*
* @public
*/
export declare class JsonMethodPath extends JsonMap<any> {
method: string;
path: string | RegExp;
constructor(method: string, path: string | RegExp);
summary(summary: string): this;
description(description: string): this;
}
/**
* Configuration options for JSON operations compatible with OpenAPI 3 specifications.
*
* Extends the OpenAPI 3 operation specification with Ts.ED-specific media type
* declarations (consumes/produces) for request and response handling.
*
* @public
*/
export interface JsonOperationOptions extends OS3Operation<JsonSchema, JsonParameter, JsonMap<JsonResponse>> {
consumes: string[];
produces: string[];
}
/**
* Represents an HTTP operation (endpoint) with complete OpenAPI metadata.
*
* JsonOperation is the core class for defining HTTP endpoints in Ts.ED, storing all
* operation-level information required for OpenAPI specification generation including:
*
* - Request parameters (path, query, header, body)
* - Response definitions with status codes
* - Security requirements
* - Tags and categorization
* - Media type handling (consumes/produces)
* - Operation metadata (summary, description, operationId)
*
* ### Usage
*
* ```typescript
* const operation = new JsonOperation()
* .summary("Create a user")
* .description("Creates a new user in the system")
* .addTags([{name: "Users"}])
* .addParameter(0, parameterMetadata)
* .addResponse(201, responseMetadata);
* ```
*
* ### Key Features
*
* - **Parameters**: Manage operation parameters by index or name
* - **Responses**: Define responses for different HTTP status codes
* - **Security**: Configure authentication and authorization
* - **Media Types**: Specify accepted and produced content types
* - **Routing**: Multiple path/method combinations per operation
*
* @public
*/
export declare class JsonOperation extends JsonMap<JsonOperationOptions> {
#private;
$kind: string;
readonly operationPaths: Map<string, JsonMethodPath>;
constructor(obj?: Partial<JsonOperationOptions>);
get response(): JsonResponse | undefined;
get status(): number;
tags(tags: OpenSpecTag[]): this;
addTags(tags: OpenSpecTag[]): this;
summary(summary: string): this;
operationId(operationId: string): this;
responses(responses: JsonMap<any>): this;
defaultStatus(status: number): this;
getStatus(): number;
setRedirection(status?: number): this;
isRedirection(status?: number): boolean | 0;
addResponse(statusCode: string | number, response: JsonResponse): this;
getResponses(): JsonMap<JsonResponse>;
getResponseOf(status: number | string): JsonResponse;
ensureResponseOf(status: number | string): JsonResponse;
getHeadersOf(status: number): Record<string, JsonHeader & {
example: string;
}>;
getContentTypeOf(status: number): any;
security(security: OpenSpecSecurity): this;
addSecurityScopes(name: string, scopes: string[]): this;
description(description: string): this;
deprecated(deprecated: boolean): this;
addAllowedGroupsParameter(allowedGroups: string[]): this;
parameters(parameters: JsonParameter[]): this;
addParameter(index: number, parameter: JsonParameter): void;
consumes(consumes: string[]): this;
produces(produces: string[]): this;
addProduce(produce: string): void;
addOperationPath(method: string, path: string | RegExp): JsonMethodPath;
getAllowedOperationPath(allowedVerbs?: string[]): JsonMethodPath[];
}