HttpController

Package: @opra/common

HttpController is the runtime class that represents a single controller node in the HTTP API tree. It holds a registry of operations, nested child controllers, declared parameters, and locally scoped types. Controllers are organized in a hierarchy — a child controller's URL path is appended to its parent's.

The @HttpController() decorator is documented in the HTTP API schema section. This page covers the runtime class instance.

---

Inheritance

DocumentElement
└── HttpController

---

Properties

Property	Type	Description
kind	'HttpController'	Always 'HttpController'.
name	string	Registry name.
path	string	URL path segment for this controller. Defaults to name.
description	string | undefined	Human-readable description.
operations	ResponsiveMap<HttpOperation>	Operations registered on this controller, keyed by name.
controllers	ResponsiveMap<HttpController>	Nested child controllers, keyed by name.
parameters	HttpParameter[]	Parameters declared on the controller (shared by all operations).
types	DataTypeMap	Types scoped to this controller.
ctor	Type | undefined	The TypeScript class constructor.
instance	any | undefined	The controller instance (set by the adapter).
isRoot	boolean	true if the controller's parent is HttpApi (not another controller).

---

Methods

findController(arg)

Finds a nested child controller by its class constructor or by path string. Searches recursively. Returns undefined if not found.

ctrl.findController('/notes');
ctrl.findController(CustomerNotesController);

findController(controller: Type): HttpController | undefined
findController(resourcePath: string): HttpController | undefined

---

findParameter(name, location?)

Finds a parameter declared on this controller (or walks up to the parent) by name and optional location ('query', 'path', 'header', 'cookie'). Name matching is case-insensitive; RegExp patterns are also supported.

ctrl.findParameter('x-tenant-id', 'header');
ctrl.findParameter('customerId', 'path');

findParameter(
  paramName: string,
  location?: 'query' | 'path' | 'header' | 'cookie'
): HttpParameter | undefined

---

getFullUrl()

Returns the fully resolved URL path for this controller (concatenation of all ancestor paths).

ctrl.getFullUrl();  // e.g. '/api/customers/:customerId/notes'

getFullUrl(): string

---

toJSON(options?)

Returns an OpraSchema.HttpController plain object for schema export.

toJSON(options?: ApiDocument.ExportOptions): OpraSchema.HttpController

---

Obtaining an HttpController instance

import { HttpController } from '@opra/common';

const ctrl = document.httpApi.findController('/customers');

if (ctrl instanceof HttpController) {
  console.log(ctrl.name);         // 'Customers'
  console.log(ctrl.path);         // '/customers'
  console.log(ctrl.isRoot);       // true

  for (const op of ctrl.operations.values()) {
    console.log(op.name, op.method);
  }
}

→ HttpApi · HttpOperation · HttpParameter