Api callbacks decorator

e2e/api-spec.json

@@ -170,7 +170,51 @@
  {
  "basic": []
  }
- ]
+ ],
+ "callbacks": {
+ "myEvent": {
+ "{$request.body#/callbackUrl}": {
+ "post": {
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Cat"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Your server returns this code if it accepts the callback"
+ }
+ }
+ }
+ }
+ },
+ "mySecondEvent": {
+ "{$request.body#/callbackUrl}": {
+ "post": {
+ "requestBody": {
+ "required": true,
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/Cat"
+ }
+ }
+ }
+ },
+ "responses": {
+ "200": {
+ "description": "Your server returns this code if it accepts the callback"
+ }
+ }
+ }
+ }
+ }
+ }
  },
  "get": {
  "operationId": "CatsController_findAll",

e2e/src/cats/cats.controller.ts

@@ -9,7 +9,9 @@ import {
  ApiQuery,
  ApiResponse,
  ApiSecurity,
- ApiTags
+ ApiTags,
+ ApiCallbacks,
+ getSchemaPath
 } from '../../../lib';
 import { CatsService } from './cats.service';
 import { Cat } from './classes/cat.class';
@@ -30,6 +32,28 @@ import { LettersEnum, PaginationQuery } from './dto/pagination-query.dto';
 export class CatsController {
  constructor(private readonly catsService: CatsService) {}
 
+ @ApiCallbacks({
+ name: 'mySecondEvent',
+ callbackUrl: '{$request.body#/callbackUrl}',
+ method: 'post',
+ requestBody: {
+ type: Cat
+ },
+ expectedResponse: {
+ status: 200
+ }
+ })
+ @ApiCallbacks({
+ name: 'myEvent',
+ callbackUrl: '{$request.body#/callbackUrl}',
+ method: 'post',
+ requestBody: {
+ type: Cat
+ },
+ expectedResponse: {
+ status: 200
+ }
+ })
  @ApiTags('create cats')
  @Post()
  @ApiOperation({ summary: 'Create cat' })

e2e/validate-schema.e2e-spec.ts

@@ -57,6 +57,20 @@ describe('Validate OpenAPI schema', () => {
  api.info.version
  );
  expect(api.info.title).toEqual('Cats example');
+ expect(
+ api.paths['/api/cats']['post']['callbacks']['myEvent'][
+ '{$request.body#/callbackUrl}'
+ ]['post']['requestBody']['content']['application/json']['schema'][
+ 'properties'
+ ]['breed']['type']
+ ).toEqual('string');
+ expect(
+ api.paths['/api/cats']['post']['callbacks']['mySecondEvent'][
+ '{$request.body#/callbackUrl}'
+ ]['post']['requestBody']['content']['application/json']['schema'][
+ 'properties'
+ ]['breed']['type']
+ ).toEqual('string');
  expect(api.paths['/api/cats']['get']['x-codeSamples'][0]['lang']).toEqual(
  'JavaScript'
  );

lib/constants.ts

@@ -5,6 +5,7 @@ export const DECORATORS = {
  API_PRODUCES: `${DECORATORS_PREFIX}/apiProduces`,
  API_CONSUMES: `${DECORATORS_PREFIX}/apiConsumes`,
  API_TAGS: `${DECORATORS_PREFIX}/apiUseTags`,
+ API_CALLBACKS: `${DECORATORS_PREFIX}/apiCallbacks`,
  API_PARAMETERS: `${DECORATORS_PREFIX}/apiParameters`,
  API_HEADERS: `${DECORATORS_PREFIX}/apiHeaders`,
  API_MODEL_PROPERTIES: `${DECORATORS_PREFIX}/apiModelProperties`,

lib/decorators/api-callbacks.decorator.ts

@@ -0,0 +1,7 @@
+import { DECORATORS } from '../constants';
+import { createMixedDecorator } from './helpers';
+import { CallBackObject } from '../interfaces/callback-object.interface'
+
+export function ApiCallbacks(...callbackObject: Array<CallBackObject<any>>) {
+ return createMixedDecorator(DECORATORS.API_CALLBACKS, callbackObject);
+}

lib/decorators/index.ts

@@ -22,4 +22,5 @@ export * from './api-query.decorator';
 export * from './api-response.decorator';
 export * from './api-security.decorator';
 export * from './api-use-tags.decorator';
+export * from './api-callbacks.decorator';
 export * from './api-extension.decorator';

lib/explorers/api-callbacks.explorer.ts

@@ -0,0 +1,49 @@
+import { Type } from '@nestjs/common';
+import { DECORATORS } from '../constants';
+import { getSchemaPath } from '../utils';
+import { CallBackObject } from '../interfaces/callback-object.interface'
+
+export const exploreApiCallbacksMetadata = (
+ instance: object,
+ prototype: Type<unknown>,
+ method: object
+) => {
+ const callbacksData = Reflect.getMetadata(DECORATORS.API_CALLBACKS, method);
+ if (!callbacksData) return callbacksData;
+
+ return callbacksData.reduce((acc, callbackData: CallBackObject<string | Function>) => {
+ const {
+ name: eventName,
+ callbackUrl,
+ method: callbackMethod,
+ requestBody,
+ expectedResponse
+ } = callbackData;
+ return {
+ ...acc,
+ [eventName]: {
+ [callbackUrl]: {
+ [callbackMethod]: {
+ requestBody: {
+ required: true,
+ content: {
+ 'application/json': {
+ schema: {
+ $ref: getSchemaPath(requestBody.type)
+ }
+ }
+ }
+ },
+ responses: {
+ [expectedResponse.status]: {
+ description:
+ expectedResponse.description ||
+ 'Your server returns this code if it accepts the callback'
+ }
+ }
+ }
+ }
+ }
+ };
+ }, {});
+};

lib/extra/swagger-shim.ts

@@ -143,6 +143,9 @@ export function ApiSecurity() {
 export function ApiTags() {
  return () => {};
 }
+export function ApiCallbacks() {
+ return () => {};
+}
 export function ApiExtension() {
  return () => {};
 }

lib/interfaces/callback-object.interface.ts

@@ -0,0 +1,12 @@
+export interface CallBackObject<T> {
+ name: string,
+ callbackUrl: string,
+ method: string,
+ requestBody: {
+ type: T
+ },
+ expectedResponse: {
+ status: number
+ description?: string
+ },
+}

lib/interfaces/denormalized-doc-resolvers.interface.ts

@@ -2,5 +2,6 @@ export interface DenormalizedDocResolvers {
  root: Function[];
  security: Function[];
  tags: Function[];
+ callbacks: Function[];
  responses: Function[];
 }

lib/swagger-explorer.ts

@@ -32,6 +32,7 @@ import {
 } from 'lodash';
 import * as pathToRegexp from 'path-to-regexp';
 import { DECORATORS } from './constants';
+import { exploreApiCallbacksMetadata } from './explorers/api-callbacks.explorer';
 import { exploreApiExcludeControllerMetadata } from './explorers/api-exclude-controller.explorer';
 import { exploreApiExcludeEndpointMetadata } from './explorers/api-exclude-endpoint.explorer';
 import {
@@ -96,6 +97,7 @@ export class SwaggerExplorer {
  ],
  security: [exploreApiSecurityMetadata],
  tags: [exploreApiTagsMetadata],
+ callbacks: [exploreApiCallbacksMetadata],
  responses: [exploreApiResponseMetadata.bind(null, this.schemas)]
  };
  return this.generateDenormalizedDocument(