Interface: ControllerSpec

Properties
Name Type Default Value Flags Description
basePath undefined | string exported optional

The base path on which the Controller API is served. If it is not included, the API is served directly under the host. The value MUST start with a leading slash (/).

components ComponentsObject exported optional

OpenAPI components.schemas generated from model metadata

paths PathObject exported

The available paths and operations for the API.

Interface: RestEndpoint

Data structure for REST related metadata

Properties
Name Type Default Value Flags Description
path string exported

Data structure for REST related metadata

spec OperationObject exported optional

Data structure for REST related metadata

verb string exported

Data structure for REST related metadata

Function: getControllerSpec

getControllerSpec(constructor: Function) : ControllerSpec

Get the controller spec for the given class

Parameters
Name Type Default Value Flags Description
constructor Function

Controller class

Function: api

api(spec: ControllerSpec) : anonymous

Decorate the given Controller constructor with metadata describing the HTTP/REST API the Controller implements/provides.

@api can be applied to controller classes. For example,

@api({basePath: '/my'})
class MyController {
  // ...
}

Parameters
Name Type Default Value Flags Description
spec ControllerSpec

OpenAPI specification describing the endpoints handled by this controller

Function: del

del(path: string, spec: OperationObject) : anonymous

Expose a Controller method as a REST API operation mapped to DELETE request method.

Parameters
Name Type Default Value Flags Description
path string

The URL path of this operation, e.g. /product/{id}

spec OperationObject optional

The OpenAPI specification describing parameters and responses of this operation.

Function: get

get(path: string, spec: OperationObject) : anonymous

Expose a Controller method as a REST API operation mapped to GET request method.

Parameters
Name Type Default Value Flags Description
path string

The URL path of this operation, e.g. /product/{id}

spec OperationObject optional

The OpenAPI specification describing parameters and responses of this operation.

Function: operation

operation(verb: string, path: string, spec: OperationObject) : anonymous

Expose a Controller method as a REST API operation.

Parameters
Name Type Default Value Flags Description
verb string

HTTP verb, e.g. GET or POST.

path string

The URL path of this operation, e.g. /product/{id}

spec OperationObject optional

The OpenAPI specification describing parameters and responses of this operation.

Function: patch

patch(path: string, spec: OperationObject) : anonymous

Expose a Controller method as a REST API operation mapped to PATCH request method.

Parameters
Name Type Default Value Flags Description
path string

The URL path of this operation, e.g. /product/{id}

spec OperationObject optional

The OpenAPI specification describing parameters and responses of this operation.

Function: post

post(path: string, spec: OperationObject) : anonymous

Expose a Controller method as a REST API operation mapped to POST request method.

Parameters
Name Type Default Value Flags Description
path string

The URL path of this operation, e.g. /product/{id}

spec OperationObject optional

The OpenAPI specification describing parameters and responses of this operation.

Function: put

put(path: string, spec: OperationObject) : anonymous

Expose a Controller method as a REST API operation mapped to PUT request method.

Parameters
Name Type Default Value Flags Description
path string

The URL path of this operation, e.g. /product/{id}

spec OperationObject optional

The OpenAPI specification describing parameters and responses of this operation.

Namespace: param

Describe an input parameter of a Controller method. The @param decorator takes an argument of ParameterObject to define how to map the parameter to OpenAPI specification.

@param(paramSpec) must be applied to parameters. For example,

class MyController {
  @get('/')
  list(
    @param(offsetSpec) offset?: number,
    @param(pageSizeSpec) pageSize?: number,
  ) {}
}

Function: param.array

param.array(name: string, source: ParameterLocation, itemSpec: SchemaObject | ReferenceObject) : (Anonymous function)

Define a parameter of array type.

Parameters
Name Type Default Value Flags Description
name string

Parameter name

source ParameterLocation

Source of the parameter value

itemSpec SchemaObject | ReferenceObject

Item type for the array or the full item object

Object literal: param.header

Describe an input parameter of a Controller method. The @param decorator takes an argument of ParameterObject to define how to map the parameter to OpenAPI specification.

@param(paramSpec) must be applied to parameters. For example,

class MyController {
  @get('/')
  list(
    @param(offsetSpec) offset?: number,
    @param(pageSizeSpec) pageSize?: number,
  ) {}
}

Variables
Name Type Default Value Flags Description
binary (Anonymous function) createParamShortcut('header', builtinTypes.binary) exported

Define a parameter of "binary" type that's read from a request header. Usage: @param.header.binary('paramName')

boolean (Anonymous function) createParamShortcut('header', builtinTypes.boolean) exported

Define a parameter of "boolean" type that's read from a request header. Usage: @param.header.boolean('paramName')

byte (Anonymous function) createParamShortcut('header', builtinTypes.byte) exported

Define a parameter of "byte" type that's read from a request header. Usage: @param.header.byte('paramName')

date (Anonymous function) createParamShortcut('header', builtinTypes.date) exported

Define a parameter of "date" type that's read from a request header. Usage: @param.header.date('paramName')

dateTime (Anonymous function) createParamShortcut('header', builtinTypes.dateTime) exported

Define a parameter of "dateTime" type that's read from a request header. Usage: @param.header.dateTime('paramName')

double (Anonymous function) createParamShortcut('header', builtinTypes.double) exported

Define a parameter of "double" type that's read from a request header. Usage: @param.header.double('paramName')

float (Anonymous function) createParamShortcut('header', builtinTypes.float) exported

Define a parameter of "float" type that's read from a request header. Usage: @param.header.float('paramName')

integer (Anonymous function) createParamShortcut('header', builtinTypes.integer) exported

Define a parameter of "integer" type that's read from a request header. Usage: @param.header.integer('paramName')

long (Anonymous function) createParamShortcut('header', builtinTypes.long) exported

Define a parameter of "long" type that's read from a request header. Usage: @param.header.long('paramName')

number (Anonymous function) createParamShortcut('header', builtinTypes.number) exported

Define a parameter of "number" type that's read from a request header. Usage: @param.header.number('paramName')

password (Anonymous function) createParamShortcut('header', builtinTypes.password) exported

Define a parameter of "password" type that's read from a request header. Usage: @param.header.password('paramName')

string (Anonymous function) createParamShortcut('header', builtinTypes.string) exported

Define a parameter of "string" type that's read from a request header. Usage: @param.header.string('paramName')

Object literal: param.path

Describe an input parameter of a Controller method. The @param decorator takes an argument of ParameterObject to define how to map the parameter to OpenAPI specification.

@param(paramSpec) must be applied to parameters. For example,

class MyController {
  @get('/')
  list(
    @param(offsetSpec) offset?: number,
    @param(pageSizeSpec) pageSize?: number,
  ) {}
}

Variables
Name Type Default Value Flags Description
binary (Anonymous function) createParamShortcut('path', builtinTypes.binary) exported

Define a parameter of "binary" type that's read from request path. Usage: @param.path.binary('paramName')

boolean (Anonymous function) createParamShortcut('path', builtinTypes.boolean) exported

Define a parameter of "boolean" type that's read from request path. Usage: @param.path.boolean('paramName')

byte (Anonymous function) createParamShortcut('path', builtinTypes.byte) exported

Define a parameter of "byte" type that's read from request path. Usage: @param.path.byte('paramName')

date (Anonymous function) createParamShortcut('path', builtinTypes.date) exported

Define a parameter of "date" type that's read from request path. Usage: @param.path.date('paramName')

dateTime (Anonymous function) createParamShortcut('path', builtinTypes.dateTime) exported

Define a parameter of "dateTime" type that's read from request path. Usage: @param.path.dateTime('paramName')

double (Anonymous function) createParamShortcut('path', builtinTypes.double) exported

Define a parameter of "double" type that's read from request path. Usage: @param.path.double('paramName')

float (Anonymous function) createParamShortcut('path', builtinTypes.float) exported

Define a parameter of "float" type that's read from request path. Usage: @param.path.float('paramName')

integer (Anonymous function) createParamShortcut('path', builtinTypes.integer) exported

Define a parameter of "integer" type that's read from request path. Usage: @param.path.integer('paramName')

long (Anonymous function) createParamShortcut('path', builtinTypes.long) exported

Define a parameter of "long" type that's read from request path. Usage: @param.path.long('paramName')

number (Anonymous function) createParamShortcut('path', builtinTypes.number) exported

Define a parameter of "number" type that's read from request path. Usage: @param.path.number('paramName')

password (Anonymous function) createParamShortcut('path', builtinTypes.password) exported

Define a parameter of "password" type that's read from request path. Usage: @param.path.password('paramName')

string (Anonymous function) createParamShortcut('path', builtinTypes.string) exported

Define a parameter of "string" type that's read from request path. Usage: @param.path.string('paramName')

Object literal: param.query

Describe an input parameter of a Controller method. The @param decorator takes an argument of ParameterObject to define how to map the parameter to OpenAPI specification.

@param(paramSpec) must be applied to parameters. For example,

class MyController {
  @get('/')
  list(
    @param(offsetSpec) offset?: number,
    @param(pageSizeSpec) pageSize?: number,
  ) {}
}

Variables
Name Type Default Value Flags Description
binary (Anonymous function) createParamShortcut('query', builtinTypes.binary) exported

Define a parameter of "binary" type that's read from the query string. Usage: @param.query.binary('paramName')

boolean (Anonymous function) createParamShortcut('query', builtinTypes.boolean) exported

Define a parameter of "boolean" type that's read from the query string. Usage: @param.query.boolean('paramName')

byte (Anonymous function) createParamShortcut('query', builtinTypes.byte) exported

Define a parameter of "byte" type that's read from the query string. Usage: @param.query.byte('paramName')

date (Anonymous function) createParamShortcut('query', builtinTypes.date) exported

Define a parameter of "date" type that's read from the query string. Usage: @param.query.date('paramName')

dateTime (Anonymous function) createParamShortcut('query', builtinTypes.dateTime) exported

Define a parameter of "dateTime" type that's read from the query string. Usage: @param.query.dateTime('paramName')

double (Anonymous function) createParamShortcut('query', builtinTypes.double) exported

Define a parameter of "double" type that's read from the query string. Usage: @param.query.double('paramName')

float (Anonymous function) createParamShortcut('query', builtinTypes.float) exported

Define a parameter of "float" type that's read from the query string. Usage: @param.query.float('paramName')

integer (Anonymous function) createParamShortcut('query', builtinTypes.integer) exported

Define a parameter of "integer" type that's read from the query string. Usage: @param.query.integer('paramName')

long (Anonymous function) createParamShortcut('query', builtinTypes.long) exported

Define a parameter of "long" type that's read from the query string. Usage: @param.query.long('paramName')

number (Anonymous function) createParamShortcut('query', builtinTypes.number) exported

Define a parameter of "number" type that's read from the query string. Usage: @param.query.number('paramName')

password (Anonymous function) createParamShortcut('query', builtinTypes.password) exported

Define a parameter of "password" type that's read from the query string. Usage: @param.query.password('paramName')

string (Anonymous function) createParamShortcut('query', builtinTypes.string) exported

Define a parameter of "integer" type that's read from the query string. Usage: @param.query.string('paramName')

Namespace: requestBody

Function: requestBody.array

requestBody.array(itemSpec: SchemaObject | ReferenceObject, properties: undefined | anonymous) : (Anonymous function)

Define a requestBody of array type.

Parameters
Name Type Default Value Flags Description
itemSpec SchemaObject | ReferenceObject

the full item object

properties undefined | anonymous optional

The requestBody properties other than content

const REQUEST_BODY_INDEX = "x-parameter-index"

Function: resolveSchema

resolveSchema(fn: Function, schema: SchemaObject) : SchemaObject

Generate the type and format property in a Schema Object according to a parameter's type. type and format will be preserved if provided in schema

Parameters
Name Type Default Value Flags Description
fn Function optional
schema SchemaObject {}

The schema object provided in an parameter object

Function: jsonOrBooleanToJSON

jsonOrBooleanToJSON(jsonOrBool: boolean | JsonSchema) : JSONSchema6

Helper function used to interpret boolean values as JSON Schemas. See http://json-schema.org/draft-06/json-schema-release-notes.html

Returns:

A JSON Schema document representing the input value.

Parameters
Name Type Default Value Flags Description
jsonOrBool boolean | JsonSchema

converts boolean values into their representative JSON Schemas

Function: jsonToSchemaObject

jsonToSchemaObject(json: JsonSchema) : SchemaObject

Converts JSON Schemas into a SchemaObject

Parameters
Name Type Default Value Flags Description
json JsonSchema

JSON Schema to convert from

Namespace: OAI3Keys

const OAI3Keys.CLASS_KEY = MetadataAccessor.create< ControllerSpec, ClassDecorator >('openapi-v3:class')

Metadata key used to set or retrieve @api metadata

const OAI3Keys.CONTROLLER_SPEC_KEY = MetadataAccessor.create< ControllerSpec, ClassDecorator >('openapi-v3:controller-spec')

Metadata key used to set or retrieve a controller spec

const OAI3Keys.METHODS_KEY = MetadataAccessor.create< Partial, MethodDecorator >('openapi-v3:methods')

Metadata key used to set or retrieve @operation metadata.

const OAI3Keys.PARAMETERS_KEY = MetadataAccessor.create< ParameterObject, ParameterDecorator >('openapi-v3:parameters')

Metadata key used to set or retrieve param decorator metadata

const OAI3Keys.REQUEST_BODY_KEY = MetadataAccessor.create< RequestBodyObject, ParameterDecorator >('openapi-v3:request-body')

Metadata key used to set or retrieve @requestBody metadata