Merge pull request #37 from samchon/feature/mixed

Fix samchon/nestia#983: mixed-in null type case.
samchon · Aug 11, 2024 · 9171a99 · 9171a99
2 parents 2aef676 + 87d2798
commit 9171a99
Show file tree

Hide file tree

Showing 6 changed files with 89 additions and 14 deletions.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@samchon/openapi",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "OpenAPI definitions and converters for 'typia' and 'nestia'.",
   "main": "./lib/index.js",
   "module": "./lib/index.mjs",

diff --git a/src/OpenApi.ts b/src/OpenApi.ts
@@ -492,13 +492,66 @@ export namespace OpenApi {
      * Parameter of the operation.
      */
     export interface IParameter<Schema extends IJsonSchema = IJsonSchema> {
+      /**
+       * Representative name of the parameter.
+       *
+       * In the most case, the `name` is equivalent to parameter variable name.
+       * Therefore, the `name` must be filled with the significant variable name
+       * of the parameter.
+       *
+       * By the way, only when the {@link in} property is `path`, the `name`
+       * can be omitted. In that case, the `name` is automatically deduced from
+       * the URL path's positional template argument analyzing.
+       */
       name?: string;
+
+      /**
+       * Location of the parameter.
+       *
+       * The `in` property is a string that determines the location of the parameter.
+       *
+       * - `path`: parameter is part of the path of the URL.
+       * - `query`: parameter is part of the query string.
+       * - `header`: parameter is part of the header.
+       * - `cookie`: parameter is part of the cookie.
+       */
       in: "path" | "query" | "header" | "cookie";
+
+      /**
+       * Type info of the parameter.
+       */
       schema: Schema;
+
+      /**
+       * Whether the parameter is required for execution or not.
+       *
+       * If the parameter is required, the value must be filled. Otherwise,
+       * it is possible to skip the parameter when executing the APi operation.
+       *
+       * For reference, the `required` property must be always `true` when the
+       * {@link in} property is `path`. Otherwise, the `required` property can
+       * be anything of them; `true`, `false` and `undefined`.
+       */
       required?: boolean;
+
+      /**
+       * Short title of the parameter.
+       */
       title?: string;
+
+      /**
+       * Verbose explanation of the parameter.
+       */
       description?: string;
+
+      /**
+       * Example value of the parameter.
+       */
       example?: any;
+
+      /**
+       * Collection of example values of the parameter with keys.
+       */
       examples?: Record<string, IExample>;
     }
 
@@ -525,9 +578,8 @@ export namespace OpenApi {
     /**
      * List of content types supported in request/response body.
      */
-    export type IContent<Schema extends IJsonSchema = IJsonSchema> = Partial<
-      Record<ContentType, IMediaType<Schema>>
-    >;
+    export interface IContent<Schema extends IJsonSchema = IJsonSchema>
+      extends Partial<Record<ContentType, IMediaType<Schema>>> {}
 
     /**
      * Media type of a request/response body.

diff --git a/src/OpenApiV3.ts b/src/OpenApiV3.ts
@@ -75,7 +75,8 @@ export namespace OpenApiV3 {
   /* -----------------------------------------------------------
     PATH ITEMS
   ----------------------------------------------------------- */
-  export type IPath = {
+  export interface IPath
+    extends Partial<Record<Method, IOperation | undefined>> {
     parameters?: Array<
       | IOperation.IParameter
       | IJsonSchema.IReference<`#/components/headers/${string}`>
@@ -84,7 +85,7 @@ export namespace OpenApiV3 {
     servers?: IServer[];
     summary?: string;
     description?: string;
-  } & Partial<Record<Method, IOperation | undefined>>;
+  }
 
   export interface IOperation {
     operationId?: string;

diff --git a/src/OpenApiV3_1.ts b/src/OpenApiV3_1.ts
@@ -81,7 +81,7 @@ export namespace OpenApiV3_1 {
   /* -----------------------------------------------------------
     OPERATORS
   ----------------------------------------------------------- */
-  export type IPath = {
+  export interface IPath extends Partial<Record<Method, IOperation>> {
     parameters?: Array<
       | IOperation.IParameter
       | IJsonSchema.IReference<`#/components/headers/${string}`>
@@ -90,7 +90,7 @@ export namespace OpenApiV3_1 {
     servers?: IServer[];
     summary?: string;
     description?: string;
-  } & Partial<Record<Method, IOperation>>;
+  }
 
   export interface IOperation {
     operationId?: string;
@@ -197,9 +197,16 @@ export namespace OpenApiV3_1 {
         Omit<IObject, "type">,
         IOneOf,
         IAnyOf,
-        IAllOf {
+        IAllOf,
+        IReference {
       type: Array<
-        "boolean" | "integer" | "number" | "string" | "array" | "object"
+        | "boolean"
+        | "integer"
+        | "number"
+        | "string"
+        | "array"
+        | "object"
+        | "null"
       >;
       default?: any[] | null;
       enum?: any[];

diff --git a/src/SwaggerV2.ts b/src/SwaggerV2.ts
@@ -68,11 +68,12 @@ export namespace SwaggerV2 {
   /* -----------------------------------------------------------
     OPERATORS
   ----------------------------------------------------------- */
-  export type IPath = {
+  export interface IPath
+    extends Partial<Record<Method, IOperation | undefined>> {
     parameters?: Array<
       IOperation.IParameter | IJsonSchema.IReference<`#/parameters/${string}`>
     >;
-  } & Partial<Record<Method, IOperation | undefined>>;
+  }
 
   export interface IOperation {
     operationId?: string;

diff --git a/src/internal/OpenApiV3_1Converter.ts b/src/internal/OpenApiV3_1Converter.ts
@@ -305,25 +305,39 @@ export namespace OpenApiV3_1Converter {
               ...{
                 type: undefined,
                 oneOf: undefined,
+                anyOf: undefined,
                 allOf: undefined,
+                $ref: undefined,
               },
             });
           if (schema.oneOf !== undefined)
             visit({
               ...schema,
               ...{
                 type: undefined,
-                const: undefined,
+                anyOf: undefined,
                 allOf: undefined,
+                $ref: undefined,
               },
             });
           if (schema.anyOf !== undefined)
             visit({
               ...schema,
               ...{
                 type: undefined,
-                const: undefined,
                 oneOf: undefined,
+                allOf: undefined,
+                $ref: undefined,
+              },
+            });
+          if (schema.allOf !== undefined)
+            visit({
+              ...schema,
+              ...{
+                type: undefined,
+                oneOf: undefined,
+                anyOf: undefined,
+                $ref: undefined,
               },
             });
           for (const type of schema.type)