Contexts

A large amount of information about operations and requests are shared across several systems. @simply-openapi/controllers passes this information in Context objects, which inherit from each other as the execution progresses from building operations to handling requests.

OperationContext

This context provides detailed information about an OpenAPI Operation.

Properties

• spec - The root OpenAPI specification passed to createMethodHandlerFromSpec.

• path - The request / operation path as it exists in the OpenAPI spec.

• method - The request / operation method.

• pathItem - The Path Item Object this operation is defined in.

• operation - The Operation Object this operation is defined in.

• securitySchemes - A record of all resolved Security Schemes defined in the OpenAPI specification, keyed by scheme name.

• securities - An array of the resolved Security Requirements for this operation. This will either be those defined by the operation itself, or if the operation does not specify any, then the security schemes of the OpenAPI document will be used.

• parameters - An array of the resolved Parameter Objects of this operation. These may come from the operation itself, or the path item.

• requestBody - The resolved Request Body Object for this operation.

OperationHandlerContext

This context provides information about a specific method handler on a controller. As methods implement operations, it inherits from OperationContext.

Properties

In addition to all properties from the OperationContext, the following properties are available:

• controller - The resolved controller class instance the handler is attached to.

• handler - The resolved handler function that will handle the operation.

• handlerArgs - An array of argument definitions describing the purpose of each argument of the handler. Note that if an argument of the handler has no definition, the value at that index will be undefined.

OperationMiddlewareFactoryContext

This context is used for producing middleware to handle methods. As middleware factories run on specific methods, this context inherits from OperationHandlerContext

Properties

In addition to all all properties from OperationHandlerContext, the following properties are available:

• validators - An object containing functions which will take an OpenAPI 3.1 Schema object, and return a function that attempts to validate and coerce its argument. If the data is valid, the cosersed value will be returned. If the data is invalid, an AJV ValidationError will be thrown with an array of AJV Errors in its errors property. For an example of this, see Schema Based Validation. The following functions are available by default. They may be modified, or new validators may be added, through the validatorFactories option of createRouterFromSpec. See here for more details.

  • createParameterValidator - Creates a validator function that validates parameter objects. The validation will coerce types, but will not apply defaults. Coercion is done in accordance with the AJV Type Coercion Rules
  • createBodyValidator - Creates a validator function that validates parameter objects. The validation will coerce types and apply defaults. Coercion is done in accordance with the AJV Type Coercion Rules
  • createResponseValidator - Creates a validator function that validates responses. No type coersion is done, and no defaults are applied; types must match exactly.

OperationRequestContext

This context is used when handling a specific network request. It inherits from the OperationHandlerContext.

Properties

In addition to all properties from the OperationHandlerContext, the following properties are available:

• req - The express request object of this request.

• res - The express response object of this request.

Methods

The following methods are available to simplify working with the request:

• getPathParam(name) - Gets the value of the path parameter of the given name. If the parameter is not set, undefined is returned.

• getHeader(name) - Gets the value of the header of the given name. This method is case insensitive. If the header is not set, undefined is returned. If the header is set more than once, an array of values is returned.

• getQuery(name) - Gets the value of the query parameter with the given name. If the query parameter is not set, undefined is returned. If the query parameter is set more than once, an array of values is returned.

• getCookie(name) - Gets the value of the cookie with the given name. If the cookie is not set, undefined is returned.

The following methods are available for working with Request Data:

• hasRequestData(key) - Returns true if the request data specified by the key was ever set, or false if it was not. This will return true in cases where the request data was explicitly set to undefined.

• getRequestData(key) - Returns the request data for the specified key if set, or undefined if not.

• setRequestData(key, value) - Sets the request data for the specified key.