Page Contents

Home > @loopback/openapi-v3

openapi-v3 package

Decorators that describe LoopBack artifacts as OpenAPI 3.0.0 metadata and utilities that transfer LoopBack metadata to OpenAPI 3.0.0 specifications.

Remarks

The package has functions described above for LoopBack controller classes. Decorators apply REST api mapping metadata to controller classes and their members. And utilities that inspect controller classes to build OpenAPI 3.0.0 specifications from REST API mapping metadata.

Functions for more artifacts will be added when needed.

Classes

Class Description
OASEnhancerService An extension point for OpenAPI Spec enhancement This service is used for enhancing an OpenAPI spec by loading and applying one or more registered enhancers.A typical use of it would be generating the OpenAPI spec for the endpoints on a server in the @loopback/rest module.

Enumerations

Enumeration Description
OperationVisibility  

Functions

Function Description
api(spec) Decorate the given Controller constructor with metadata describing the HTTP/REST API the Controller implements/provides.@api can be applied to controller classes.
createEmptyApiSpec() Create an empty OpenApiSpec object that’s still a valid openapi document.
del(path, spec) Expose a Controller method as a REST API operation mapped to DELETE request method.
deprecated(isDeprecated) Marks an api path as deprecated. When applied to a class, this decorator marks all paths as deprecated.You can optionally mark all controllers in a class as deprecated, but use @deprecated(false) on a specific method to ensure it is not marked as deprecated in the specification.
get(path, spec) Expose a Controller method as a REST API operation mapped to GET request method.
getControllerSpec(constructor) Get the controller spec for the given class
getFilterSchemaFor(modelCtor, options) Build an OpenAPI schema describing the format of the “filter” object used to query model instances.Note we don’t take the model properties into account yet and return a generic json schema allowing any “where” condition.
getModelSchemaRef(modelCtor, options) Describe the provided Model as a reference to a definition shared by multiple endpoints. The definition is included in the returned schema.
getWhereSchemaFor(modelCtor) Build a OpenAPI schema describing the format of the “where” object used to filter model instances to query, update or delete.Note we don’t take the model properties into account yet and return a generic json schema allowing any “where” condition.
jsonOrBooleanToJSON(jsonOrBool) Helper function used to interpret boolean values as JSON Schemas. See http://json-schema.org/draft-06/json-schema-release-notes.html
jsonToSchemaObject(json, visited) Converts JSON Schemas into a SchemaObject
mergeOpenAPISpec(currentSpec, patchSpec) The default merge function to patch the current OpenAPI spec. It leverages module json-merge-patch’s merge API to merge two json objects. It returns a new merged object without modifying the original one.A list of merging rules can be found in test file: https://github.com/pierreinglebert/json-merge-patch/blob/master/test/lib/merge.js
mergeSecuritySchemeToSpec(spec, schemeName, schemeSpec) Security scheme merge helper function to patch the current OpenAPI spec. It provides a direct route to add a security schema to the specs components. It returns a new merged object without modifying the original one.
operation(verb, path, spec) Expose a Controller method as a REST API operation.
param(paramSpec) Describe an input parameter of a Controller method.@param must be applied to parameters.
patch(path, spec) Expose a Controller method as a REST API operation mapped to PATCH request method.
post(path, spec) Expose a Controller method as a REST API operation mapped to POST request method.
put(path, spec) Expose a Controller method as a REST API operation mapped to PUT request method.
requestBody(requestBodySpec) Describe the request body of a Controller method parameter.A typical OpenAPI requestBody spec contains property: - description - required - content.
response(responseCode, responseModelOrSpec) Add response object to a path spec.
tags(tagNames) Add tags for an endpoint. When applied to a class, this decorator adds the tags to all endpoints.
visibility(visibilityType) Marks an api path with the specfied visibility. When applied to a class, this decorator marks all paths with the specified visibility.You can optionally mark all controllers in a class with @visibility('undocumented'), but use @visibility('documented') on a specific method to ensure it is not marked as undocumented.

Interfaces

Interface Description
ControllerSpec  
OASEnhancer Typically an extension point defines an interface as the contract for extensions to implement
OASEnhancerServiceOptions Options for the OpenAPI Spec enhancer extension point
ResponseDecoratorMetadataItem  
RestEndpoint Data structure for REST related metadata
TagsDecoratorMetadata  

Namespaces

Namespace Description
OASEnhancerBindings  
param Namespace for @param.* decorators
requestBody  
response  

Variables

Variable Description
asSpecEnhancer A binding template for spec contributor extensions
DEFAULT_OPENAPI_SPEC_INFO  
oas  
REQUEST_BODY_INDEX  
TS_TYPE_KEY  

Type Aliases

Type Alias Description
OpenApiSpec  
ResponseDecoratorMetadata  
ResponseModelOrSpec  
SchemaRef Custom LoopBack extension: a reference to Schema object that’s bundled inside definitions property.