[Core] Improve Interface for swagger documentation

Author: dnphu

src/api/core/document.ts

@@ -1,20 +1,22 @@
 import { OPEN_API_VERSION } from 'src/constants';
 import { Validate } from 'src/utils/validate';
-import { InfoDoc, SwaggerDoc, TagDoc } from './interfaces/document.interface';
+import {
+  ExternalDoc,
+  InfoDoc,
+  ServerDoc,
+  SwaggerDoc,
+} from './interfaces/document.interface';
 
 export class DocumentBuilder {
   private document: SwaggerDoc = { openapi: OPEN_API_VERSION };
 
-  public addTags(tags: TagDoc[]): DocumentBuilder {
-    tags.forEach((tag: TagDoc) => {
-      Validate.assertNotEmpty(
-        tag.name,
-        'Missing name when define tag in swagger',
-      );
-      Validate.assertString(tag.name, `Tag: ${tag.name} should be a string`);
-    });
+  public setExternalDocs(externalDoc: ExternalDoc): DocumentBuilder {
+    this.document.externalDocs = externalDoc;
+    return this;
+  }
 
-    this.document.tags = tags;
+  public setServers(...servers: ServerDoc[]) {
+    this.document.servers = servers;
     return this;
   }
 

src/api/core/interfaces/document.interface.ts

@@ -1,10 +1,12 @@
+import { SchemaDoc } from './schema-doc';
+
 export interface SwaggerDoc {
   readonly openapi: string;
   info?: InfoDoc;
   externalDocs?: ExternalDoc;
   servers?: ServerDoc[];
   tags?: TagDoc[];
-  paths?: any;
+  paths?: PathDoc;
   components?: ComponentDoc;
 }
 
@@ -52,11 +54,40 @@ export interface ExternalDoc {
   url?: string;
 }
 
+// Component document
 export interface ComponentDoc {
-  schemas: any;
-  securitySchemes: {
-    [authKey: string]: SecurityDoc | BearerAuthDoc | ApiKeyDoc;
-  };
+  schemas: Record<string, SchemaDoc> | RefDoc;
+  securitySchemes:
+    | Record<string, SecurityDoc | BearerAuthDoc | ApiKeyDoc>
+    | RefDoc;
+  responses: Record<string, ResponseDoc> | RefDoc;
+  parameters: Record<string, ParameterDoc> | RefDoc;
+  examples: any | RefDoc;
+  requestBodies: any | RefDoc;
+  headers: any | RefDoc;
+  links: any | RefDoc;
+  callbacks: any | RefDoc;
+}
+
+export interface RefDoc {
+  $ref: string;
+}
+
+export interface ResponseDoc {
+  description?: string;
+  headers?: Record<string, any> | RefDoc;
+  content?: Record<string, any>;
+  links?: Record<string, any> | RefDoc;
+}
+
+export type PathLocation = 'query' | 'header' | 'path' | 'cookie';
+export interface ParameterDoc {
+  name: string;
+  in: PathLocation;
+  description?: string;
+  required?: boolean;
+  deprecated?: string;
+  allowEmptyValue?: boolean;
 }
 
 /**
@@ -98,3 +129,24 @@ export type ApiKeyDoc = {
   name: 'api_key';
   in: 'header';
 };
+
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch';
+
+export interface PathDoc {
+  [path: string]: HttpMethod;
+}
+
+export interface OperationDoc {
+  tags: string[];
+  summary: string;
+  description: string;
+  externalDocs: ExternalDoc;
+  operationId: string;
+  parameters: ParameterDoc[];
+  requestBody: any;
+  responses: Record<string, ResponseDoc>;
+  callbacks: any;
+  deprecated: boolean;
+  security: SecurityDoc[];
+  servers: ServerDoc;
+}

src/api/core/interfaces/schema-doc.ts

@@ -0,0 +1,92 @@
+import { ExternalDoc } from './document.interface';
+
+export interface SchemaRootDoc {
+  type: string;
+  properties?: Record<string, SchemaRootDoc>;
+  required?: string[];
+  allOf?: SchemaRootDoc;
+  oneOf?: SchemaRootDoc;
+  anyOf?: SchemaRootDoc;
+  not?: SchemaRootDoc;
+  items?: Record<string, any>; // Must contains when type is array
+  additionalProperties?: boolean | SchemaRootDoc;
+  description?: string;
+  format?: string;
+  default?: any;
+  nullable: boolean;
+  discriminator?: any;
+  readOnly: boolean;
+  writeOnly: boolean;
+  xml?: any;
+  externalDocs: ExternalDoc;
+  example?: any;
+  deprecated: boolean;
+}
+
+export type IntType = {
+  type: 'interger';
+  format: 'int32';
+};
+
+export type LongType = {
+  type: 'interger';
+  format: 'int64';
+};
+
+export type FloatType = {
+  type: 'number';
+  format: 'float';
+};
+
+export type DoubleType = {
+  type: 'number';
+  format: 'double';
+};
+
+export type StringType = {
+  type: 'string';
+};
+
+export type ByteType = {
+  type: 'string';
+  format: 'byte';
+};
+
+export type BinaryType = {
+  type: 'string';
+  format: 'binary';
+};
+
+export type BooleanType = {
+  type: 'boolean';
+};
+
+export type DateType = {
+  type: 'string';
+  format: 'date';
+};
+
+export type DateTimeType = {
+  type: 'string';
+  format: 'date-time';
+};
+
+export type PasswordType = {
+  type: 'string';
+  format: 'password';
+};
+
+export type DataTypes =
+  | IntType
+  | LongType
+  | FloatType
+  | DoubleType
+  | StringType
+  | ByteType
+  | BinaryType
+  | BooleanType
+  | DateType
+  | DateTimeType
+  | PasswordType;
+
+export type SchemaDoc = DataTypes & SchemaRootDoc;