feat(server): beta.17 - sockets swagger support (#197)

serhiisol · Aug 30, 2023 · eca468a · eca468a
1 parent c49b967
commit eca468a
Show file tree

Hide file tree

Showing 14 changed files with 131 additions and 23 deletions.
diff --git a/server/package-lock.json b/server/package-lock.json
diff --git a/server/package.json b/server/package.json
@@ -148,5 +148,5 @@
       ]
     }
   },
-  "version": "1.0.0-beta.16"
+  "version": "1.0.0-beta.17"
 }
diff --git a/server/src/core/helpers/decorators.ts b/server/src/core/helpers/decorators.ts
@@ -1,9 +1,9 @@
-import { ParamMetadata } from '../types';
+import { MethodMetadata, ParamMetadata } from '../types';
 import { extractParamNames } from '../utils';
 import { METHOD_METADATA, PARAM_TYPE_METADATA, PARAMS_METADATA, RETURN_TYPE_METADATA } from './constants';
 import { Context } from './context';
 
-export function paramDecoratorFactory(metadata: Partial<ParamMetadata>) {
+export function paramDecoratorFactory(metadata: Partial<ParamMetadata> & { [key: string]: any; }) {
   return function (target: InstanceType<any>, methodName: string, index: number) {
     const params = Reflect.getMetadata(PARAMS_METADATA, target[methodName]) ?? [];
     const argType = Reflect.getMetadata(PARAM_TYPE_METADATA, target, methodName)[index];
@@ -27,7 +27,7 @@ export function paramDecoratorFactory(metadata: Partial<ParamMetadata>) {
   };
 }
 
-export function methodDecoratorFactory(metadata: object) {
+export function methodDecoratorFactory(metadata: Partial<MethodMetadata> & { [key: string]: any; }) {
   return (target: object, methodName: string, descriptor: TypedPropertyDescriptor<any>) => {
     const methods = Reflect.getMetadata(METHOD_METADATA, target.constructor) ?? [];
     const returnType = Reflect.getMetadata(RETURN_TYPE_METADATA, target, methodName);

diff --git a/server/src/core/types.ts b/server/src/core/types.ts
@@ -27,6 +27,7 @@ export interface ControllerMetadata {
 export interface MethodMetadata {
   methodName: string;
   returnType: ClassConstructor;
+  source: string;
   type: string;
   url: string;
 }

diff --git a/server/src/platforms/http/decorators/route.ts b/server/src/platforms/http/decorators/route.ts
@@ -1,32 +1,66 @@
 import { Decorate, methodDecoratorFactory } from '../../../core';
-import { HttpMethodType, METHOD_TEMPLATE_METADATA } from '../helpers';
+import { HttpMethodType, METHOD_TEMPLATE_METADATA, SOURCE_TYPE } from '../helpers';
 
 export function Delete(url = '', status?: number) {
-  return methodDecoratorFactory({ status, type: HttpMethodType.DELETE, url });
+  return methodDecoratorFactory({
+    source: SOURCE_TYPE,
+    status,
+    type: HttpMethodType.DELETE,
+    url,
+  });
 }
 
 export function Get(url = '', status?: number) {
-  return methodDecoratorFactory({ status, type: HttpMethodType.GET, url });
+  return methodDecoratorFactory({
+    status,
+    type: HttpMethodType.GET,
+    url,
+  });
 }
 
 export function Head(url = '', status?: number) {
-  return methodDecoratorFactory({ status, type: HttpMethodType.HEAD, url });
+  return methodDecoratorFactory({
+    source: SOURCE_TYPE,
+    status,
+    type: HttpMethodType.HEAD,
+    url,
+  });
 }
 
 export function Options(url = '', status?: number) {
-  return methodDecoratorFactory({ status, type: HttpMethodType.OPTIONS, url });
+  return methodDecoratorFactory({
+    source: SOURCE_TYPE,
+    status,
+    type: HttpMethodType.OPTIONS,
+    url,
+  });
 }
 
 export function Patch(url = '', status?: number) {
-  return methodDecoratorFactory({ status, type: HttpMethodType.PATCH, url });
+  return methodDecoratorFactory({
+    source: SOURCE_TYPE,
+    status,
+    type: HttpMethodType.PATCH,
+    url,
+  });
 }
 
 export function Post(url = '', status?: number) {
-  return methodDecoratorFactory({ status, type: HttpMethodType.POST, url });
+  return methodDecoratorFactory({
+    source: SOURCE_TYPE,
+    status,
+    type: HttpMethodType.POST,
+    url,
+  });
 }
 
 export function Put(url = '', status?: number) {
-  return methodDecoratorFactory({ status, type: HttpMethodType.PUT, url });
+  return methodDecoratorFactory({
+    source: SOURCE_TYPE,
+    status,
+    type: HttpMethodType.PUT,
+    url,
+  });
 }
 
 export function Render(template: string) {

diff --git a/server/src/platforms/http/helpers/constants/index.ts b/server/src/platforms/http/helpers/constants/index.ts
@@ -2,3 +2,4 @@ export * from './constants';
 export * from './http-method-type';
 export * from './injectables';
 export * from './parameter-type';
+export * from './source-type';
diff --git a/server/src/platforms/http/helpers/constants/source-type.ts b/server/src/platforms/http/helpers/constants/source-type.ts
@@ -0,0 +1 @@
+export const SOURCE_TYPE = 'http';
diff --git a/server/src/platforms/http/index.ts b/server/src/platforms/http/index.ts
@@ -1,4 +1,4 @@
 export * from './decorators';
-export { HTTP_ADAPTER, HttpApplicationAdapter, HttpContext, ParameterType } from './helpers';
+export { HTTP_ADAPTER, HttpApplicationAdapter, HttpContext, HttpMethodType, ParameterType, SOURCE_TYPE } from './helpers';
 export * from './http.module';
 export { AdapterRoute, RouteMetadata } from './types';
diff --git a/server/src/platforms/sockets/decorators/events.ts b/server/src/platforms/sockets/decorators/events.ts
@@ -1,27 +1,31 @@
 import { methodDecoratorFactory } from '../../../core';
-import { EventType } from '../helpers';
+import { EventType, SOURCE_TYPE } from '../helpers';
 
 export function Connection() {
   return methodDecoratorFactory({
+    source: SOURCE_TYPE,
     type: EventType.CONNECTION,
   });
 }
 
 export function Disconnect() {
   return methodDecoratorFactory({
+    source: SOURCE_TYPE,
     type: EventType.DISCONNECT,
   });
 }
 
 export function Disconnecting() {
   return methodDecoratorFactory({
+    source: SOURCE_TYPE,
     type: EventType.DISCONNECTING,
   });
 }
 
 export function Event(event: string) {
   return methodDecoratorFactory({
     event,
+    source: SOURCE_TYPE,
     type: EventType.EVENT,
   });
 }
diff --git a/server/src/platforms/sockets/helpers/constants/index.ts b/server/src/platforms/sockets/helpers/constants/index.ts
@@ -1,3 +1,4 @@
 export * from './event-type';
 export * from './injectables';
 export * from './parameter-type';
+export * from './source-type';
diff --git a/server/src/platforms/sockets/helpers/constants/source-type.ts b/server/src/platforms/sockets/helpers/constants/source-type.ts
@@ -0,0 +1 @@
+export const SOURCE_TYPE = 'sockets';
diff --git a/server/src/platforms/sockets/index.ts b/server/src/platforms/sockets/index.ts
@@ -1,4 +1,4 @@
 export * from './decorators';
-export { ParameterType, SOCKETS_ADAPTER, SocketsApplicationAdapter, SocketsContext } from './helpers';
+export { ParameterType, SOCKETS_ADAPTER, SocketsApplicationAdapter, SocketsContext, SOURCE_TYPE } from './helpers';
 export * from './sockets.module';
 export { AdapterEvent, EventMetadata } from './types';
diff --git a/server/src/platforms/swagger/helpers/swagger-ui/swagger-document.ts b/server/src/platforms/swagger/helpers/swagger-ui/swagger-document.ts
@@ -2,11 +2,15 @@ import { Inject, Injectable, Optional } from '@decorators/di';
 import { OpenAPIV3_1 } from 'openapi-types';
 
 import { APP_VERSION, ClassConstructor, Handler, MetadataScanner, Reflector } from '../../../../core';
-import { ParameterType, RouteMetadata } from '../../../http';
+import { HttpMethodType, ParameterType, RouteMetadata } from '../../../http';
+import { SOURCE_TYPE as SOCKETS_SOURCE_TYPE } from '../../../sockets';
 import { ApiResponse, SwaggerConfig } from '../../types';
-import { METHOD_API_RESPONSE_METADATA, METHOD_API_RESPONSES_METADATA, METHOD_API_SECURITY_METADATA, PROPERTY_API_PARAMETER_METADATA, SWAGGER_CONFIG } from '../constants';
+import { METHOD_API_OPERATION_METADATA, METHOD_API_RESPONSE_METADATA, METHOD_API_RESPONSES_METADATA, METHOD_API_SECURITY_METADATA, PROPERTY_API_PARAMETER_METADATA, SWAGGER_CONFIG } from '../constants';
 import { getValidationMeta, isStandardType, pick, replaceUrlParameters, typeToContentType } from './utils';
 
+export const DEFAULT_STATUS = 200;
+export const DEFAULT_METHOD = HttpMethodType.POST;
+
 @Injectable()
 export class SwaggerDocument {
   private paths = {};
@@ -53,6 +57,10 @@ export class SwaggerDocument {
       METHOD_API_RESPONSES_METADATA,
       route.controller.prototype[route.methodName],
     );
+    const operationMeta = this.reflector.getMetadata(
+      METHOD_API_OPERATION_METADATA,
+      route.controller.prototype[route.methodName],
+    );
 
     const ctrlMethod = `${route.controller.name}.${route.methodName}`;
 
@@ -79,19 +87,27 @@ export class SwaggerDocument {
       };
     }
 
-    const preResponses = { [route.status]: { type: route.returnType, ...simpleMeta }, ...detailedMeta };
+    const preResponses = {
+      [route.status || DEFAULT_STATUS]: { type: route.returnType, ...simpleMeta },
+      ...detailedMeta,
+    };
     const responses = Object.keys(preResponses).reduce((acc, status) => ({
       ...acc, [status]: this.toResponse(preResponses[status], route.methodName),
     }), {});
 
     const security = this.securitySchemas[ctrlMethod] ? [{ [ctrlMethod]: [] }] : [];
 
+    const tag = route.source === SOCKETS_SOURCE_TYPE
+      ? `Sockets :: ${route.controller.name}`
+      : route.controller.name;
+
     return {
+      ...operationMeta,
       parameters,
       requestBody,
       responses,
       security,
-      tags: [route.controller.name],
+      tags: [tag],
     } as OpenAPIV3_1.OperationObject;
   }
 
@@ -165,11 +181,18 @@ export class SwaggerDocument {
         this.securitySchemas[`${route.controller.name}.${route.methodName}`] = meta;
       }
 
-      const url = replaceUrlParameters(route.url);
+      const rawUrl = replaceUrlParameters(route.url);
+      const url = route.source === SOCKETS_SOURCE_TYPE
+        ? `${rawUrl} => ${route.type}` + (route['event'] ? ` => ${route['event']}` : '')
+        : rawUrl;
+
+      const methodType = route.source === SOCKETS_SOURCE_TYPE
+        ? DEFAULT_METHOD
+        : route.type;
 
       this.paths[url] = {
         ...(this.paths[url] ?? {}),
-        [route.type]: this.getPath(route),
+        [methodType]: this.getPath(route),
       };
     }
   }

diff --git a/server/src/platforms/swagger/helpers/swagger-ui/swagger-resolver.ts b/server/src/platforms/swagger/helpers/swagger-ui/swagger-resolver.ts
@@ -80,7 +80,27 @@ function initializerScriptContent(jsonPath: string) {
         ],
         layout: "StandaloneLayout"
       });
+
+      onSwaggerUIReady(disableSocketsTryItOut);
     };
+
+    function onSwaggerUIReady(fn) {
+      const interval = setInterval(() => {
+        if (document.getElementById('swagger-ui')) {
+          clearInterval(interval);
+
+          fn();
+        }
+      }, 100);
+    }
+
+    function disableSocketsTryItOut() {
+      const socketEvents = [...document.querySelectorAll('[data-tag^="sockets" i]')];
+
+      for (const el of socketEvents) {
+        el.parentElement.classList.add('server-swagger-sockets');
+      }
+    }
   `;
 }
 
@@ -90,6 +110,28 @@ function indexStyles(theme: SwaggerConfig['theme']) {
 
   const styleOverrides = `
     ${styles}
+
+    .server-swagger-sockets .try-out {
+      display: none;
+    }
+
+    .server-swagger-sockets .opblock-summary-method {
+      overflow: hidden;
+      position: relative;
+    }
+
+    .server-swagger-sockets .opblock-summary-method::after {
+      align-items: center;
+      background-color: #a748cb;
+      bottom: 0;
+      content: 'SOCKETS';
+      display: flex;
+      justify-content: center;
+      left: 0;
+      position: absolute;
+      right: 0;
+      top: 0;
+    }
   `;
 
   if (theme === 'light') {
-Original file line number
+Diff line change
@@ Expand Up / @@ -148,5 +148,5 @@ @@
           ]
         }
       },
-      "version": "1.0.0-beta.16"
+      "version": "1.0.0-beta.17"
     }