bazis 0.98.4 → 0.98.6

package/core/http/Decorators/metadata.ts

@@ -54,15 +54,24 @@ function emptyMeta(): ControllerMeta {
   return { isController: false, middleware: [], filters: [], catches: [], actions: new Map() };
 }
 
+/**
+ * Actions of a subclass whose routes are still the base class's. The first
+ * route decorator of the subclass on such a method replaces them instead of
+ * adding a second, duplicate route.
+ */
+const inheritedRoutes = new WeakSet<ActionMeta>();
+
 function cloneMeta(source: ControllerMeta): ControllerMeta {
   const actions = new Map<string | symbol, ActionMeta>();
   for (const [name, action] of source.actions) {
-    actions.set(name, {
+    const copy: ActionMeta = {
       ...action,
       routes: [...action.routes],
       middleware: [...action.middleware],
       filters: [...action.filters],
-    });
+    };
+    if (copy.routes.length > 0) inheritedRoutes.add(copy);
+    actions.set(name, copy);
   }
   return {
     ...source,
@@ -98,6 +107,17 @@ export function ownActionMeta(metadata: object, methodName: string | symbol): Ac
   return action;
 }
 
+/**
+ * Routes of an action for a route decorator to add to. Routes inherited from
+ * the base class are dropped first: a subclass that declares routes on an
+ * overriding method replaces the base method's routes. Other settings of the
+ * base method (status code, middleware, version) stay inherited.
+ */
+export function ownRoutes(action: ActionMeta): RouteDeclaration[] {
+  if (inheritedRoutes.delete(action)) action.routes = [];
+  return action.routes;
+}
+
 /** Reads controller metadata from a class (undefined if not decorated). */
 export function controllerMetaOf(ctor: object): ControllerMeta | undefined {
   const metadata = (ctor as { [key: symbol]: unknown })[Symbol.metadata as unknown as symbol] as

package/core/http/Decorators/routes.ts

@@ -1,6 +1,6 @@
 import type { HttpMiddleware } from "../Middleware/types";
 import { HttpSetupError } from "../Errors/HttpError";
-import { ownActionMeta } from "./metadata";
+import { ownActionMeta, ownRoutes } from "./metadata";
 
 type MethodDecorator = (value: (...args: never[]) => unknown, context: ClassMethodDecoratorContext) => void;
 
@@ -39,7 +39,7 @@ function route(httpMethod: string, templateOrOptions?: string | RouteOptions, ma
       throw new Error(`HTTP route decorators support public instance methods only ("${String(context.name)}").`);
     }
     const action = ownActionMeta(context.metadata, context.name);
-    action.routes.push({ httpMethod, template });
+    ownRoutes(action).push({ httpMethod, template });
     if (options) {
       // Options apply to the whole action (like attribute decorators); with
       // several route decorators scalar fields are overwritten and

package/core/http/OpenApi/openApiDocument.ts

@@ -25,12 +25,28 @@ export interface HttpOpenApiDocumentBuildInput {
   readonly version: string;
 }
 
+/** Body of every error response: `{ "error": "...", "details": ... }` (see Middleware/errorHandler). */
+const ERROR_SCHEMA_NAME = "HttpErrorResponse";
+const ERROR_SCHEMA: OpenApiSchema = {
+  type: "object",
+  description: "Error response of the bazis HTTP server.",
+  properties: {
+    error: { type: "string", description: "Human-readable error message." },
+    details: { description: "Error details, for example the list of validation errors." },
+  },
+  required: ["error"],
+};
+const ERROR_DESCRIPTIONS: Readonly<Record<number, string>> = {
+  400: "Bad Request", 401: "Unauthorized", 403: "Forbidden", 404: "Not Found", 409: "Conflict",
+  413: "Payload Too Large", 415: "Unsupported Media Type", 429: "Too Many Requests",
+};
+
 export function buildHttpOpenApiDocument(input: HttpOpenApiDocumentBuildInput): OpenApiSchema {
   const generated = getGeneratedOpenApiMetadata(input.controllers);
   const documentInput: LibraryOpenApiDocumentBuildInput = {
     title: input.title,
     version: input.version,
-    schemas: generated.schemas,
+    schemas: { [ERROR_SCHEMA_NAME]: ERROR_SCHEMA, ...generated.schemas },
     operations: collectOpenApiOperations(input, generated),
     generatedBy: "bazis:di-generate",
   };
@@ -89,16 +105,18 @@ function createOperation(input: CreateOperationInput): OpenApiCatalogOperation {
   const version = input.action.version ?? input.meta.version;
   const auth = resolveAuthorizeMeta(input.controllerClass, input.methodName);
   const generatedOperation = input.generated.operations[input.controllerClass.name]?.[methodName];
-  const status = String(successStatus(input.httpMethod, input.action));
+  const status = String(successStatus(input.httpMethod, input.action, generatedOperation?.status));
   const responseSchema = generatedOperation?.response;
   const contentType = input.action.produces ?? "application/json";
+  const authorized = !auth.allowAnonymous && auth.authorize !== undefined;
 
   return {
     path: input.path,
     httpMethod: input.httpMethod,
     tag: tagName(input.meta, input.controllerClass),
     operationId: stableHttpOperationId(input.httpMethod, input.path),
-    summary: `${normalizedMethod(input.httpMethod)} ${input.path}`,
+    summary: generatedOperation?.summary ?? `${normalizedMethod(input.httpMethod)} ${input.path}`,
+    ...(generatedOperation?.description !== undefined ? { description: generatedOperation.description } : {}),
     parameters: collectParameters(
       input.bindings,
       input.versioning,
@@ -117,8 +135,9 @@ function createOperation(input: CreateOperationInput): OpenApiCatalogOperation {
             },
           }
         : { description: "Success" },
+      ...errorResponses(errorStatuses(input.bindings, authorized, generatedOperation?.errors)),
     },
-    authorized: !auth.allowAnonymous && auth.authorize !== undefined,
+    authorized,
     ...(version !== undefined ? { versions: [version] } : {}),
   };
 }
@@ -305,11 +324,42 @@ function schemaForConstraint(constraint: string | undefined): OpenApiSchema {
   }
 }
 
-function successStatus(method: string, action: ActionMeta): number {
-  if (action.httpCode !== undefined) {
-    return action.httpCode;
+function successStatus(method: string, action: ActionMeta, generated: number | undefined): number {
+  return action.httpCode ?? generated ?? (method === "DELETE" ? 204 : 200);
+}
+
+/**
+ * Errors the operation can answer with: 400 when the request carries values
+ * that are converted or validated (body, list query, query, typed route
+ * parameters), 401/403 under @Authorize, and the errors the method body
+ * returns or throws itself.
+ */
+function errorStatuses(
+  bindings: readonly ParameterBinding[],
+  authorized: boolean,
+  generated: readonly number[] | undefined,
+): number[] {
+  const statuses = new Set(generated ?? []);
+  const validated = bindings.some((binding) =>
+    binding.source === "body" || binding.source === "list" || binding.source === "query"
+    || (binding.source === "route" && binding.type !== undefined && binding.type !== "string"));
+  if (validated) statuses.add(400);
+  if (authorized) {
+    statuses.add(401);
+    statuses.add(403);
+  }
+  return [...statuses].sort((a, b) => a - b);
+}
+
+function errorResponses(statuses: readonly number[]): Record<string, OpenApiSchema> {
+  const responses: Record<string, OpenApiSchema> = {};
+  for (const status of statuses) {
+    responses[String(status)] = {
+      description: ERROR_DESCRIPTIONS[status] ?? "Error",
+      content: { "application/json": { schema: { $ref: `#/components/schemas/${ERROR_SCHEMA_NAME}` } } },
+    };
   }
-  return method === "DELETE" ? 204 : 200;
+  return responses;
 }
 
 function tagName(meta: ControllerMeta, controllerClass: Class<object>): string {

package/core/http/SPEC.md

@@ -228,6 +228,26 @@ class DerivedController extends BaseController {}
 // DerivedController inherits sharedMiddleware
 ```
 
+Routes are inherited too, which is how a new API version is built on the old one:
+
+```ts
+@Controller("notes") @ApiVersion("2")
+class NotesV2Controller extends NotesV1Controller {
+  @Get(":noteId") override getById(noteId: string) { ... } // replaces GET :id of v1
+  override text(id: string) { ... }                         // keeps the v1 route
+}
+```
+
+- A method the subclass does not override keeps its routes, served by the base implementation.
+- An override without route decorators keeps the base method's routes; its own parameters are bound.
+- Route decorators on an override replace the base method's routes (since 0.98.5; before, they
+  were added to them, and startup failed with a duplicate route). Other settings of the base
+  method — status code, middleware, version — stay inherited.
+
+Codegen follows the `extends` chain, so inherited actions get argument bindings for the subclass
+(since 0.98.5; before, a subclass without own route decorators got none, and an override received
+`HttpContext` in place of its parameters).
+
 ### The equivalent through inline route options
 
 `RouteOptions.middleware` on `@Get`/`@Post` writes into the same `ActionMeta.middleware`:

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.4" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.6" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/scripts/di-generate.ts

@@ -1089,12 +1089,11 @@ function hasDecorator(node: ts.HasDecorators, name: string): boolean {
  * template, parsed like `Routing/template.ts` (`:name`, `:name(int)`, `*name`,
  * and a bare `*` named `rest`).
  */
-function routeParamNames(method: ts.MethodDeclaration): Set<string> {
+function routeParamNames(controller: ts.ClassDeclaration, method: ts.MethodDeclaration): Set<string> {
   const names = new Set<string>();
   const templates: string[] = [];
-  const owner = method.parent;
   const sources: readonly [readonly ts.Decorator[], (name: string) => boolean][] = [
-    [ts.isClassDeclaration(owner) ? ts.getDecorators(owner) ?? [] : [], (name) => name === "Controller"],
+    [ts.getDecorators(controller) ?? [], (name) => name === "Controller"],
     [ts.getDecorators(method) ?? [], (name) => ROUTE_DECORATORS.has(name)],
   ];
   for (const [decorators, accepts] of sources) {
@@ -1361,8 +1360,7 @@ function collectOpenApiOperation(controllerName: string, method: ts.MethodDeclar
   if (!ts.isIdentifier(method.name)) {
     return;
   }
-  const response = openApiCodegen.responseSchemaFromMethod(method);
-  (openApiOperations[controllerName] ??= {})[method.name.text] = response === undefined ? {} : { response };
+  (openApiOperations[controllerName] ??= {})[method.name.text] = openApiCodegen.operationFromMethod(method);
 }
 
 /** True if the class has an `extends ListRequest` (with or without type args). */
@@ -1394,23 +1392,9 @@ function collectControllerBindings(node: ts.ClassDeclaration, controllerName: st
   }
   httpControllerFiles[controllerName] = filePath;
 
-  for (const member of node.members) {
-    if (!ts.isMethodDeclaration(member) || !ts.isIdentifier(member.name)) {
-      continue;
-    }
-    const decorators = ts.getDecorators(member) ?? [];
-    const hasRoute = decorators.some((decorator) => {
-      const info = decoratorCall(decorator);
-      return info !== undefined && ROUTE_DECORATORS.has(info.name);
-    });
-    if (hasRoute) {
-      collectOpenApiOperation(controllerName, member);
-    }
-    if (!hasRoute) {
-      continue;
-    }
-
-    const routeParams = routeParamNames(member);
+  for (const { name, routes, member } of controllerActions(node)) {
+    collectOpenApiOperation(controllerName, member);
+    const routeParams = routeParamNames(node, routes);
     const specs: HttpBindingSpec[] = [];
     let bodyCount = 0;
     let failed: string | undefined;
@@ -1469,15 +1453,59 @@ function collectControllerBindings(node: ts.ClassDeclaration, controllerName: st
 
     if (failed) {
       fatalErrors.push(
-        `BAZIS_HTTP_BINDING_UNRESOLVED: controller "${controllerName}.${member.name.text}" (${filePath}): cannot infer bindings (${failed}). ` +
+        `BAZIS_HTTP_BINDING_UNRESOLVED: controller "${controllerName}.${name}" (${filePath}): cannot infer bindings (${failed}). ` +
           `Use supported parameter types; read headers or raw bodies through HttpContext, and inject services in the constructor.`,
       );
       continue;
     }
-    (httpBindings[controllerName] ??= {})[member.name.text] = specs;
+    (httpBindings[controllerName] ??= {})[name] = specs;
   }
 }
 
+interface ControllerAction {
+  readonly name: string;
+  /** Declaration whose route decorators give the routes. */
+  readonly routes: ts.MethodDeclaration;
+  /** Declaration that runs: its parameters are bound. */
+  readonly member: ts.MethodDeclaration;
+}
+
+/**
+ * Route methods of a controller, including those inherited from base classes,
+ * as the runtime sees them: the nearest declaration with route decorators
+ * gives the routes (a subclass's own decorators replace the base's), the
+ * nearest implementation gives the parameters (an override without
+ * decorators keeps the base routes with its own signature).
+ */
+function controllerActions(node: ts.ClassDeclaration): ControllerAction[] {
+  const routes = new Map<string, ts.MethodDeclaration>();
+  const members = new Map<string, ts.MethodDeclaration>();
+  const seen = new Set<ts.ClassDeclaration>();
+  for (let current: ts.ClassDeclaration | undefined = node; current && !seen.has(current); current = baseClassDeclaration(current)) {
+    seen.add(current);
+    for (const member of current.members) {
+      if (!ts.isMethodDeclaration(member) || !ts.isIdentifier(member.name)) continue;
+      const name = member.name.text;
+      if (!members.has(name) && member.body !== undefined) members.set(name, member);
+      if (!routes.has(name) && hasRouteDecorator(member)) routes.set(name, member);
+    }
+  }
+  return [...routes].map(([name, declaration]) => ({ name, routes: declaration, member: members.get(name) ?? declaration }));
+}
+
+function hasRouteDecorator(member: ts.MethodDeclaration): boolean {
+  return (ts.getDecorators(member) ?? []).some((decorator) => {
+    const info = decoratorCall(decorator);
+    return info !== undefined && ROUTE_DECORATORS.has(info.name);
+  });
+}
+
+function baseClassDeclaration(node: ts.ClassDeclaration): ts.ClassDeclaration | undefined {
+  const clause = node.heritageClauses?.find((item) => item.token === ts.SyntaxKind.ExtendsKeyword);
+  const base = clause?.types[0]?.expression;
+  return base === undefined ? undefined : classDeclarationForExpression(base);
+}
+
 /** `limit = 100` has no type annotation — infer the primitive from the default value. */
 function inferTypeFromInitializer(initializer: ts.Expression | undefined): HttpBindingSpec["type"] | undefined {
   if (!initializer) {

package/library/openapi/codegen.ts

@@ -5,6 +5,14 @@ export type OpenApiCodegenSchema = Record<string, unknown>;
 
 export interface OpenApiCodegenOperationSpec {
   readonly response?: OpenApiCodegenSchema;
+  /** Success status when every success return uses the same result helper (`Created` -> 201). */
+  readonly status?: number;
+  /** Error statuses returned (`NotFound(...)`) or thrown (`throw new NotFoundError()`) in the method body. */
+  readonly errors?: readonly number[];
+  /** First line of the method's JSDoc. */
+  readonly summary?: string;
+  /** The rest of the method's JSDoc. */
+  readonly description?: string;
 }
 
 export interface OpenApiCodegenAnalyzer {
@@ -15,6 +23,8 @@ export interface OpenApiCodegenAnalyzer {
   schemaFromDeclaration(declaration: ts.ClassDeclaration | ts.InterfaceDeclaration): OpenApiCodegenSchema;
   schemaNameForDeclaration(name: string, declaration: ts.Declaration | undefined): string;
   responseSchemaFromMethod(method: ts.MethodDeclaration): OpenApiCodegenSchema | undefined;
+  /** Response schema, statuses and JSDoc of a controller method. */
+  operationFromMethod(method: ts.MethodDeclaration): OpenApiCodegenOperationSpec;
 }
 
 export interface OpenApiCodegenAnalyzerInput {
@@ -32,6 +42,14 @@ const SUCCESS_RESULT_HELPERS = new Set(["Ok", "Accepted"]);
 const CREATED_RESULT_HELPERS = new Set(["Created"]);
 const EMPTY_SUCCESS_RESULT_HELPERS = new Set(["NoContent", "Redirect", "File"]);
 const ERROR_RESULT_HELPERS = new Set(["BadRequest", "Unauthorized", "Forbidden", "NotFound", "Conflict", "InternalServerError"]);
+const SUCCESS_HELPER_STATUS: Readonly<Record<string, number>> = { Ok: 200, Accepted: 202, Created: 201, NoContent: 204 };
+const ERROR_HELPER_STATUS: Readonly<Record<string, number>> = {
+  BadRequest: 400, Unauthorized: 401, Forbidden: 403, NotFound: 404, Conflict: 409,
+};
+const ERROR_CLASS_STATUS: Readonly<Record<string, number>> = {
+  BadRequestError: 400, UnauthorizedError: 401, ForbiddenError: 403, NotFoundError: 404,
+  PayloadTooLargeError: 413, UnsupportedMediaTypeError: 415, TooManyRequestsError: 429,
+};
 const OPENAPI_EMPTY_TYPE_NAMES = new Set(["HttpResult", "Response", "Blob", "ReadableStream", "Uint8Array"]);
 const OPENAPI_BUILTIN_TYPE_NAMES = new Set([
   "Array",
@@ -77,7 +95,8 @@ export function createOpenApiCodegenAnalyzer(input: OpenApiCodegenAnalyzerInput)
       const baseSchema = typeNode ? schemaFromTypeNode(typeNode) : schemaFromInitializer(schemaInitializer(member));
       const validators = validatorOptionsOf(member);
       const schema = validators.reduce((current, options) => applyValidatorOptions(current, options), baseSchema);
-      properties[name] = schema;
+      const description = documentationOf(member.name);
+      properties[name] = description === undefined ? schema : { ...schema, description };
       if (isRequiredProperty(member, ownerKind, validators)) {
         required.push(name);
       }
@@ -89,12 +108,95 @@ export function createOpenApiCodegenAnalyzer(input: OpenApiCodegenAnalyzerInput)
     return schema;
   };
 
-  const responseSchemaFromMethod = (method: ts.MethodDeclaration): OpenApiCodegenSchema | undefined => {
-    const inferred = responseSchemaFromReturnExpressions(method);
-    if (inferred !== undefined) {
-      return inferred;
+  /** JSDoc text of a declaration name, without tags; undefined when there is none. */
+  const documentationOf = (name: ts.Node): string | undefined => {
+    const symbol = checker.getSymbolAtLocation(name);
+    const text = symbol === undefined ? "" : ts.displayPartsToString(symbol.getDocumentationComment(checker)).trim();
+    return text.length > 0 ? text : undefined;
+  };
+
+  const operationFromMethod = (method: ts.MethodDeclaration): OpenApiCodegenOperationSpec => {
+    const response = responseSchemaFromMethod(method);
+    const { status, errors } = statusesFromMethod(method);
+    const documentation = documentationOf(method.name);
+    const [summary, ...rest] = documentation?.split(/\r?\n/) ?? [];
+    const description = rest.join("\n").trim();
+    return {
+      ...(response !== undefined ? { response } : {}),
+      ...(status !== undefined ? { status } : {}),
+      ...(errors.length > 0 ? { errors } : {}),
+      ...(summary !== undefined && summary.trim().length > 0 ? { summary: summary.trim() } : {}),
+      ...(description.length > 0 ? { description } : {}),
+    };
+  };
+
+  /**
+   * Success and error statuses visible in the method body: result helpers in
+   * `return` statements and `throw new <HttpError subclass>`. Errors thrown
+   * by called services are not visible here.
+   */
+  const statusesFromMethod = (method: ts.MethodDeclaration): { status?: number; errors: number[] } => {
+    const success = new Set<number>();
+    const errors = new Set<number>();
+    const addReturn = (expression: ts.Expression): void => {
+      const unwrapped = unwrapExpression(expression);
+      if (ts.isConditionalExpression(unwrapped)) {
+        addReturn(unwrapped.whenTrue);
+        addReturn(unwrapped.whenFalse);
+        return;
+      }
+      const name = ts.isCallExpression(unwrapped) ? callExpressionName(unwrapped) : undefined;
+      if (name !== undefined && SUCCESS_HELPER_STATUS[name] !== undefined) {
+        success.add(SUCCESS_HELPER_STATUS[name]);
+      } else if (name !== undefined && ERROR_HELPER_STATUS[name] !== undefined) {
+        errors.add(ERROR_HELPER_STATUS[name]);
+      } else if (name === "StatusCode" && ts.isCallExpression(unwrapped)) {
+        const status = numericLiteralValue(unwrapped.arguments[0]);
+        if (status === undefined) success.add(-1);
+        else if (status >= 400 && status < 500) errors.add(status);
+        else if (status >= 200 && status < 300) success.add(status);
+      } else if (name === undefined || !EMPTY_SUCCESS_RESULT_HELPERS.has(name) && !ERROR_RESULT_HELPERS.has(name)) {
+        success.add(200);
+      } else {
+        success.add(-1);
+      }
+    };
+    const visit = (node: ts.Node): void => {
+      if (node !== method.body && isNestedFunctionLike(node)) return;
+      if (ts.isReturnStatement(node)) {
+        if (node.expression !== undefined) addReturn(node.expression);
+        return;
+      }
+      if (ts.isThrowStatement(node) && ts.isNewExpression(unwrapExpression(node.expression))) {
+        const status = httpErrorStatus(checker.getTypeAtLocation(node.expression));
+        if (status !== undefined) errors.add(status);
+      }
+      ts.forEachChild(node, visit);
+    };
+    if (method.body !== undefined) ts.forEachChild(method.body, visit);
+    const [only] = success;
+    return {
+      ...(success.size === 1 && only !== undefined && only !== 200 && only !== -1 ? { status: only } : {}),
+      errors: [...errors].sort((a, b) => a - b),
+    };
+  };
+
+  /** Status of an HttpError subclass by its class chain (`class TaskNotFound extends NotFoundError`). */
+  const httpErrorStatus = (type: ts.Type): number | undefined => {
+    let current: ts.Type | undefined = type;
+    for (let depth = 0; current !== undefined && depth < 16; depth += 1) {
+      const name = current.getSymbol()?.getName();
+      if (name !== undefined && ERROR_CLASS_STATUS[name] !== undefined) return ERROR_CLASS_STATUS[name];
+      current = current.isClass() ? checker.getBaseTypes(current)[0] : undefined;
     }
-    return method.type ? responseSchemaFromType(method.type) : undefined;
+    return undefined;
+  };
+
+  const responseSchemaFromMethod = (method: ts.MethodDeclaration): OpenApiCodegenSchema | undefined => {
+    // A declared return type is the contract; result-helper types
+    // (HttpResult, Response) carry no schema and fall back to the returns.
+    const declared = method.type ? responseSchemaFromType(method.type) : undefined;
+    return declared ?? responseSchemaFromReturnExpressions(method);
   };
 
   const schemaFromTypeNode = (node: ts.TypeNode): OpenApiCodegenSchema => {
@@ -418,21 +520,28 @@ export function createOpenApiCodegenAnalyzer(input: OpenApiCodegenAnalyzerInput)
   return {
     schemaFromMembers,
     schemaFromDeclaration(declaration) {
-      if (!declaration.heritageClauses?.some(clause => clause.token === ts.SyntaxKind.ExtendsKeyword)) {
-        return schemaFromMembers(declaration.members, ts.isClassDeclaration(declaration) ? "class" : "interface");
-      }
-      // Effective instance properties include imported and indirect base classes.
-      // Keep original property declarations so their Validator rules remain visible.
-      const properties = checker.getPropertiesOfType(checker.getTypeAtLocation(declaration));
-      const members = properties.flatMap(property => {
-        const member = property.valueDeclaration ?? property.declarations?.[0];
-        return member !== undefined && (ts.isPropertyDeclaration(member) || ts.isPropertySignature(member)) ? [member] : [];
-      });
-      return schemaFromMembers(members, ts.isClassDeclaration(declaration) ? "class" : "interface");
+      const schema = schemaFromDeclarationMembers(declaration);
+      const description = declaration.name === undefined ? undefined : documentationOf(declaration.name);
+      return description === undefined ? schema : { description, ...schema };
     },
     schemaNameForDeclaration,
     responseSchemaFromMethod,
+    operationFromMethod,
   };
+
+  function schemaFromDeclarationMembers(declaration: ts.ClassDeclaration | ts.InterfaceDeclaration): OpenApiCodegenSchema {
+    if (!declaration.heritageClauses?.some(clause => clause.token === ts.SyntaxKind.ExtendsKeyword)) {
+      return schemaFromMembers(declaration.members, ts.isClassDeclaration(declaration) ? "class" : "interface");
+    }
+    // Effective instance properties include imported and indirect base classes.
+    // Keep original property declarations so their Validator rules remain visible.
+    const properties = checker.getPropertiesOfType(checker.getTypeAtLocation(declaration));
+    const members = properties.flatMap(property => {
+      const member = property.valueDeclaration ?? property.declarations?.[0];
+      return member !== undefined && (ts.isPropertyDeclaration(member) || ts.isPropertySignature(member)) ? [member] : [];
+    });
+    return schemaFromMembers(members, ts.isClassDeclaration(declaration) ? "class" : "interface");
+  }
 }
 
 function collectSchemaNameIndex(sourceFiles: readonly ts.SourceFile[]): Map<string, Set<string>> {

package/library/openapi/document.ts

@@ -4,6 +4,7 @@ type OpenApiOperation = {
   tags: string[];
   operationId: string;
   summary: string;
+  description?: string;
   parameters?: OpenApiParameter[];
   requestBody?: OpenApiSchema;
   responses: Record<string, OpenApiSchema>;
@@ -152,6 +153,9 @@ function operationFromCatalog(item: OpenApiCatalogOperation): OpenApiOperation {
     summary: item.summary ?? `${normalizedMethod(item.httpMethod)} ${item.path}`,
     responses: { ...item.responses },
   };
+  if (item.description !== undefined) {
+    operation.description = item.description;
+  }
   const parameters = mergeParameters(item.parameters ?? []);
   if (parameters.length > 0) {
     operation.parameters = parameters;

package/library/openapi/types.ts

@@ -2,6 +2,14 @@ export type OpenApiSchema = Readonly<Record<string, unknown>>;
 
 export interface GeneratedOpenApiOperationMetadata {
   readonly response?: OpenApiSchema;
+  /** Success status from the method's result helpers (`Created` -> 201). */
+  readonly status?: number;
+  /** Error statuses returned or thrown in the method body. */
+  readonly errors?: readonly number[];
+  /** First line of the method's JSDoc. */
+  readonly summary?: string;
+  /** The rest of the method's JSDoc. */
+  readonly description?: string;
 }
 
 export interface GeneratedOpenApiMetadata {
@@ -53,6 +61,7 @@ export interface OpenApiCatalogOperation {
   readonly tag: string;
   readonly operationId: string;
   readonly summary?: string;
+  readonly description?: string;
   readonly parameters?: readonly OpenApiParameter[];
   readonly requestBody?: OpenApiSchema;
   readonly responses: Readonly<Record<string, OpenApiSchema>>;

package/library/openapi/ui.ts

@@ -148,7 +148,7 @@ export function renderOpenApiHtml(title: string, specPath: string): string {
       method.textContent = row.method;
       const summary = document.createElement("span");
       summary.className = "summary";
-      summary.textContent = row.operation.operationId || row.operation.summary || "";
+      summary.textContent = row.operation.summary || row.operation.operationId || "";
       line.append(method, summary);
       node.appendChild(line);
       const meta = document.createElement("div");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.4",
+  "version": "0.98.6",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",