Merge pull request #24 from samchon/features/description

Documentation of `OpenApi`.
samchon · Jul 3, 2024 · abf243a · abf243a
2 parents df52923 + 6afb456
commit abf243a
Show file tree

Hide file tree

Showing 3 changed files with 787 additions and 35 deletions.
diff --git a/README.md b/README.md
@@ -19,23 +19,23 @@ Also, `@samchon/openapi` provides emended OpenAPI v3.1 definition and its conver
 
 For example, when representing nullable type, OpenAPI v3.1 supports three ways. In that case, OpenApi remains only the third way, so that makes `typia` and `nestia` (especially [`@nestia/editor`](https://nestia.io/docs/editor/)) to be simple and easy to implement.
 
-  - `{ type: ["string", "null"] }`
-  - `{ type: "string", nullable: true }`
-  - `{ oneOf: [{ type: "string" }, { type: "null" }] }`
+- `{ type: ["string", "null"] }`
+- `{ type: "string", nullable: true }`
+- `{ oneOf: [{ type: "string" }, { type: "null" }] }`
 
 Here is the entire list of differences between OpenAPI v3.1 and emended OpenApi.
 
-  - Operation
-    - Merge `OpenApiV3_1.IPathItem.parameters` to `OpenApi.IOperation.parameters`
-    - Resolve references of `OpenApiV3_1.IOperation` members
-  - JSON Schema
-    - Decompose mixed type: `OpenApiV3_1.IJsonSchema.IMixed`
-    - Resolve nullable property: `OpenApiV3_1.IJsonSchema.__ISignificant.nullable`
-    - Array type utilizes only single `OpenAPI.IJsonSchema.IArray.items`
-    - Tuple type utilizes only `OpenApi.IJsonSchema.ITuple.prefixItems`
-    - Merge `OpenApiV3_1.IJsonSchema.IAnyOf` to `OpenApi.IJsonSchema.IOneOf`
-    - Merge `OpenApiV3_1.IJsonSchema.IRecursiveReference` to `OpenApi.IJsonSchema.IReference`
-    - Merge `OpenApiV3_1.IJsonSchema.IAllOf` to `OpenApi.IJsonSchema.IObject`
+- Operation
+  - Merge `OpenApiV3_1.IPathItem.parameters` to `OpenApi.IOperation.parameters`
+  - Resolve references of `OpenApiV3_1.IOperation` members
+- JSON Schema
+  - Decompose mixed type: `OpenApiV3_1.IJsonSchema.IMixed`
+  - Resolve nullable property: `OpenApiV3_1.IJsonSchema.__ISignificant.nullable`
+  - Array type utilizes only single `OpenAPI.IJsonSchema.IArray.items`
+  - Tuple type utilizes only `OpenApi.IJsonSchema.ITuple.prefixItems`
+  - Merge `OpenApiV3_1.IJsonSchema.IAnyOf` to `OpenApi.IJsonSchema.IOneOf`
+  - Merge `OpenApiV3_1.IJsonSchema.IRecursiveReference` to `OpenApi.IJsonSchema.IReference`
+  - Merge `OpenApiV3_1.IJsonSchema.IAllOf` to `OpenApi.IJsonSchema.IObject`
 
 Additionally, `@samchon/openapi` provides [`IMigrateDocument`](https://github.com/samchon/openapi/blob/master/src/IMigrateDocument.ts) for OpenAPI generators.
 
@@ -80,7 +80,8 @@ const migrate: IMigrateDocument = OpenApi.migrate(output);
 
 
 
+
 ## Related Projects
-  - `typia`: https://github.com/samchon/typia
-  - `nestia`: https://github.com/samchon/nestia
-  - `@nestia/editor`: https://nestia.io/docs/editor
+- `typia`: https://github.com/samchon/typia
+- `nestia`: https://github.com/samchon/nestia
+- `@wrtnio/openai-function-schema`: https://github.com/wrtnio/openai-function-schema
diff --git a/src/IMigrateRoute.ts b/src/IMigrateRoute.ts
@@ -172,45 +172,116 @@ export interface IMigrateRoute<
   operation: () => Operation;
 }
 export namespace IMigrateRoute {
+  /**
+   * Metadata of path parameter.
+   */
   export interface IParameter<
     Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema,
   > {
+    /**
+     * Name of the path parameter.
+     */
     name: string;
+
+    /**
+     * Key of the path parameter.
+     */
     key: string;
+
+    /**
+     * Metadata of path parameter data type.
+     */
     schema: Schema;
+
+    /**
+     * Description comment for the path parameter.
+     */
     description?: string;
   }
+
+  /**
+   * Metadata of headers.
+   */
   export interface IHeaders<
     Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema,
   > {
-    name: string; // headers
-    key: string; // headers
+    /**
+     * Name of the headers parameter.
+     */
+    name: string;
+
+    /**
+     * Key of the headers parameter.
+     */
+    key: string;
+
+    /**
+     * Metadata of headers data type.
+     */
     schema: Schema;
   }
+
+  /**
+   * Metadata of query values.
+   */
   export interface IQuery<
     Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema,
   > {
     name: string;
     key: string;
     schema: Schema;
   }
+
+  /**
+   * Metadata of request/response body.
+   */
   export interface IBody<
     Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema,
   > {
+    /**
+     * Name of the body parameter.
+     */
     name: string;
+
+    /**
+     * Key of the body parameter.
+     */
     key: string;
+
+    /**
+     * Content type of the body.
+     */
     type:
       | "text/plain"
       | "application/json"
       | "application/x-www-form-urlencoded"
       | "multipart/form-data";
+
+    /**
+     * Metadata of response body data type.
+     */
     schema: Schema;
+
+    /**
+     * Whether the body is encrypted or not.
+     */
     "x-nestia-encrypted"?: boolean;
   }
+
+  /**
+   * Metadata of response body for exceptional status cases.
+   */
   export interface IException<
     Schema extends OpenApi.IJsonSchema = OpenApi.IJsonSchema,
   > {
+    /**
+     * Description comment for the exception.
+     */
     description?: string;
+
+    /**
+     * Metadata of response body data type.
+     */
     schema: Schema;
   }
 }