Merge pull request #536 from tomchinery/feature/#195-api-extension-de…

…corator

feat(api-extension): add support for open api extensions via decorator (#195)

e2e/api-spec.json

@@ -224,6 +224,9 @@
     "/api/cats": {
       "post": {
         "operationId": "CatsController_create",
+        "x-foo": {
+          "test": "bar "
+        },
         "summary": "Create cat",
         "parameters": [],
         "requestBody": {

e2e/src/cats/cats.controller.ts

@@ -5,6 +5,7 @@ import {
   ApiOperation,
   ApiResponse,
   ApiSecurity,
+  ApiExtension,
   ApiTags
 } from '../../../lib';
 import { CatsService } from './cats.service';
@@ -28,6 +29,7 @@ export class CatsController {
     type: () => Cat
   })
   @ApiResponse({ status: 403, description: 'Forbidden.' })
+  @ApiExtension('x-foo', { test: 'bar ' })
   async create(@Body() createCatDto: CreateCatDto): Promise<Cat> {
     return this.catsService.create(createCatDto);
   }

lib/constants.ts

@@ -11,5 +11,6 @@ export const DECORATORS = {
   API_MODEL_PROPERTIES_ARRAY: `${DECORATORS_PREFIX}/apiModelPropertiesArray`,
   API_SECURITY: `${DECORATORS_PREFIX}/apiSecurity`,
   API_EXCLUDE_ENDPOINT: `${DECORATORS_PREFIX}/apiExcludeEndpoint`,
-  API_EXTRA_MODELS: `${DECORATORS_PREFIX}/apiExtraModels`
+  API_EXTRA_MODELS: `${DECORATORS_PREFIX}/apiExtraModels`,
+  API_EXTENSION: `${DECORATORS_PREFIX}/apiExtension`
 };

lib/decorators/api-extension.decorator.ts

@@ -0,0 +1,18 @@
+import { DECORATORS } from '../constants';
+import { createMixedDecorator } from './helpers';
+
+export function ApiExtension(extensionKey: string, extensionProperties: any) {
+  if (!extensionKey.startsWith('x-')) {
+    throw new Error(
+      'Extension key is not prefixed. Please ensure you prefix it with `x-`.'
+    );
+  }
+
+  const extensionObject = {
+    [extensionKey]: {
+      ...extensionProperties
+    }
+  };
+
+  return createMixedDecorator(DECORATORS.API_EXTENSION, extensionObject);
+}

lib/decorators/index.ts

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

lib/swagger-explorer.ts

@@ -203,10 +203,12 @@ export class SwaggerExplorer {
       method
     ) as RequestMethod;
     const fullPath = globalPath + this.validateRoutePath(routePath);
+    const apiExtension = Reflect.getMetadata(DECORATORS.API_EXTENSION, method);
     return {
       method: RequestMethod[requestMethod].toLowerCase(),
       path: fullPath === '' ? '/' : fullPath,
-      operationId: this.getOperationId(instance, method)
+      operationId: this.getOperationId(instance, method),
+      ...apiExtension
     };
   }