@samchon/openapi - npm Package Compare versions

Comparing version 0.2.1 to 0.2.2

lib/IMigrateDocument.d.ts

 import { IMigrateRoute } from "./IMigrateRoute";
 import { OpenApi } from "./OpenApi";
+/**
+ * Document of migration.
+ *
+ * The `IMigrateDocument` interface is a document of migration from
+ * {@link OpenAPI.IDocument OpenAPI document} to RPC (Remote Procedure Call)
+ * functions; {@link IMigrateRoute}.
+ *
+ * As the `IMigrateDocument` and {@link IMigrateRoute} have a lot of special
+ * stories, when you're developing OpenAPI generator library, please read
+ * their descriptions carefully including the description of properties.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export interface IMigrateDocument {
+    /**
+     * List of routes for migration.
+     */
     routes: IMigrateRoute[];
+    /**
+     * List of errors occurred during the migration.
+     */
     errors: IMigrateDocument.IError[];
 }
 export declare namespace IMigrateDocument {
+    /**
+     * Error of migration in the operation level.
+     */
     interface IError {
+        /**
+         * Target operation causing the error.
+         */
         operation: () => OpenApi.IOperation;
+        /**
+         * Method of the operation.
+         *
+         * If the {@link OpenApi.IOperation.method} is not one of below type
+         * values, the operation would be ignored in the migration process for
+         * the RPC (Remote Procedure Call) function.
+         */
         method: "head" | "get" | "post" | "put" | "patch" | "delete";
+        /**
+         * Original path from the OpenAPI document.
+         */
         path: string;
+        /**
+         * List of error messages (reasons).
+         */
         messages: string[];
     }
 }

lib/IMigrateRoute.d.ts

 import { OpenApi } from "./OpenApi";
+/**
+ * Route information for migration.
+ *
+ * The `IMigrateRoute` is a structure representing a route information for
+ * OpenAPI generated RPC (Remote Procedure Call) function composed from the
+ * {@link OpenApi.IOperation OpenAPI operation}.
+ *
+ * As the `IMigrateRoute` has a lot of speical stories, when you're developing
+ * OpenAPI generator library, please read its description carefully including
+ * the description of its properties.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export interface IMigrateRoute {
+    /**
+     * Method of the route.
+     *
+     * If the {@link OpenApi.IOperation.method} is not one of below type
+     * values, the operation would be ignored in the migration process for
+     * the RPC (Remote Procedure Call) function.
+     */
     method: "head" | "get" | "post" | "put" | "patch" | "delete";
+    /**
+     * Original path from the OpenAPI document.
+     */
     path: string;
+    /**
+     * Emended path for OpenAPI generator libraries.
+     *
+     * The difference between {@link path} is:
+     *
+     * 1. Path parameters are replaced with `:param` format.
+     * 2. Empty sub-paths are removed.
+     * 3. Do not starts with `/`.
+     */
     emendedPath: string;
+    /**
+     * Accessor for the route.
+     *
+     * The `accessor` is a list of string values that are representing how to
+     * access to the OpenAPI generated RPC (Remote Procedure Call) function
+     * through namespace(s).
+     *
+     * The `accessor` is composed with the following rules. At first, namespaces
+     * are composed by static directory names in the {@link path}. Parametric
+     * symbols represented by `:param` or `{param}` cannot be a part of the
+     * namespace.
+     *
+     * Instead, they would be a part of the function name. The function
+     * name is composed with the {@link method HTTP method} and parametric symbols
+     * like `getByParam` or `postByParam`. If there are multiple path parameters,
+     * they would be concatenated by `And` like `getByParam1AndParam2`.
+     *
+     * For refefence, if the {@link operation}'s {@link method} is `delete`, the
+     * function name would be replaced to `erase` instead of `delete`. It is
+     * the reason why the `delete` is a reserved keyword in many programming
+     * languages.
+     *
+     * - Exxample 1
+     *   - path: `POST /shopping/sellers/sales`
+     *   - accessor: `shopping.sellers.sales.post`
+     * - Example 2
+     *   - endpoint: `GET /shoppings/sellers/sales/:saleId/reviews/:reviewId/comments/:id
+     *   - accessor: `shoppings.sellers.sales.reviews.getBySaleIdAndReviewIdAndCommentId`
+     */
     accessor: string[];
+    /**
+     * List of path parameters.
+     */
     parameters: IMigrateRoute.IParameter[];
+    /**
+     * Metadata of headers.
+     *
+     * The `headers` property is a metadata of HTTP request headers for RPC function,
+     * including the parameter variable name and schema.
+     *
+     * Also, its {@link IMigrateRoute.IHeaders.schema} is always object or reference
+     * to object. Even though the original {@link OpenApi.IOperation OpenAPI operation}'s
+     * headers are separated to atomic typed properties, the `headers` property forcibly
+     * combines them into a single object type.
+     *
+     * For reference, if the `headers` property has been converted to an object type
+     * forcibly, its property {@link IMigrateRoute.IHeaders.name name} and
+     * {@link IMigrateRoute.IHeaders.key key} are always "headers".
+     */
     headers: IMigrateRoute.IHeaders | null;
+    /**
+     * Metadata of query values.
+     *
+     * The `query` property is a metadata of HTTP request query values for RPC function,
+     * including the parameter variable name and schema.
+     *
+     * Also, its {@link IMigrateRoute.IQuery.schema} is always object or reference
+     * to object. Even though the original {@link OpenApi.IOperation OpenAPI operation}'s
+     * query parameters are separated to atomic typed properties, the `query` property
+     * forcibly combines them into a single object type.
+     *
+     * For reference, if the `query` property has been converted to an object type
+     * forcibly, its property {@link IMigrateRoute.IQuery.name name} and
+     * {@link IMigrateRoute.IQuery.key key} are always "headers".
+     */
     query: IMigrateRoute.IQuery | null;
+    /**
+     * Metadata of request body.
+     *
+     * The `body` property is a metadata of HTTP request body for RPC function,
+     * including the parameter variable name, content type, and schema.
+     *
+     * If the `body` property is `null`, it means the operation does not require
+     * the request body data.
+     */
     body: IMigrateRoute.IBody | null;
+    /**
+     * Metadata of response body for success case.
+     *
+     * The `success` property is a metadata of HTTP response body for RPC function,
+     * including content type, and schema when status code is `200` or `201`.
+     *
+     * If the `success` property is `null`, it means the operation does not have
+     * the response body data. In other words, the RPC function would return `void`.
+     */
     success: IMigrateRoute.IBody | null;
+    /**
+     * Metadata of response body for exceptional status cases.
+     *
+     * The `exceptions` property is a metadata of HTTP response body for RPC
+     * function, including content type, and schema when status code is not `200`
+     * or `201`.
+     *
+     * The key of the `exceptions` property is the status code. It may be a
+     * stringified number, but sometimes it could be a string like "default",
+     * because the OpenAPI document allows the status code to be a string.
+     */
     exceptions: Record<string, IMigrateRoute.IException>;
+    /**
+     * Description comment for the route function.
+     *
+     * The `comment` is a function returning description comment for the
+     * RPC function of OpenAPI generated. The comment is composed with the
+     * following rules:
+     *
+     * 1. Starts from the {@link OpenApi.IOperation.summary} paragraph.
+     * 2. The next paragraphs are filled with {@link OpenApi.IOperation.description}.
+     * 3. Parameter descriptions are added with `@param` tag.
+     * 4. Security requirements are added with `@security` tag.
+     * 5. Tag names are added with `@tag` tag.
+     * 6. If {@link OpenApi.IOperation.deprecated}, `@deprecated` tag is added.
+     */
     comment: () => string;
+    /**
+     * Original operation from the OpenAPI document.
+     *
+     * The `operation` is a function returning the original
+     * {@link OpenApi.IOperation} from the {@link OpenAPI} document.
+     */
     operation: () => OpenApi.IOperation;
@@ -15,0 +158,0 @@ }

lib/internal/MigrateConverter.js

@@ -5,3 +5,3 @@ "use strict";
 const StringUtil_1 = require("../utils/StringUtil");
-const MigrateOperationConverter_1 = require("./MigrateOperationConverter");
+const MigrateRouteConverter_1 = require("./MigrateRouteConverter");
 const MigrateRouteAccessor_1 = require("./MigrateRouteAccessor");
@@ -18,3 +18,3 @@ var MigrateConverter;
             const operation = collection[method];
-            const migrated = MigrateOperationConverter_1.MigrateOperationConverter.convert({
+            const migrated = MigrateRouteConverter_1.MigrateRouteConverter.convert({
                 document,
@@ -21,0 +21,0 @@ method,

lib/internal/OpenApiTypeChecker.d.ts

@@ -13,4 +13,4 @@ import { OpenApi } from "../OpenApi";
     const isObject: (schema: OpenApi.IJsonSchema) => schema is OpenApi.IJsonSchema.IObject;
-    const isReference: (schema: OpenApi.IJsonSchema) => schema is OpenApi.IJsonSchema.IReference<string>;
+    const isReference: (schema: OpenApi.IJsonSchema) => schema is OpenApi.IJsonSchema.IReference;
     const isOneOf: (schema: OpenApi.IJsonSchema) => schema is OpenApi.IJsonSchema.IOneOf;
 }

lib/internal/OpenApiV3Converter.d.ts

@@ -14,3 +14,3 @@ import { OpenApi } from "../OpenApi";
         const isObject: (schema: OpenApiV3.IJsonSchema) => schema is OpenApiV3.IJsonSchema.IObject;
-        const isReference: (schema: OpenApiV3.IJsonSchema) => schema is OpenApiV3.IJsonSchema.IReference<string>;
+        const isReference: (schema: OpenApiV3.IJsonSchema) => schema is OpenApiV3.IJsonSchema.IReference;
         const isAllOf: (schema: OpenApiV3.IJsonSchema) => schema is OpenApiV3.IJsonSchema.IAllOf;
@@ -17,0 +17,0 @@ const isAnyOf: (schema: OpenApiV3.IJsonSchema) => schema is OpenApiV3.IJsonSchema.IAnyOf;

lib/utils/NamingConvention.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pascal = exports.camel = exports.snake = void 0;
+exports.snake = snake;
+exports.camel = camel;
+exports.pascal = pascal;
 const StringUtil_1 = require("./StringUtil");
@@ -32,3 +34,2 @@ function snake(str) {
 }
-exports.snake = snake;
 function camel(str) {
@@ -44,3 +45,2 @@ return unsnake((str) => {
 }
-exports.camel = camel;
 function pascal(str) {
@@ -56,3 +56,2 @@ return unsnake((str) => {
 }
-exports.pascal = pascal;
 const unsnake = (escaper) => (str) => {
@@ -59,0 +58,0 @@ // eslint-disable-next-line @typescript-eslint/no-unused-vars

package.json

 {
   "name": "@samchon/openapi",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "OpenAPI definitions and converters for 'typia' and 'nestia'.",
@@ -36,6 +36,6 @@ "main": "./lib/index.js",
     "rimraf": "^5.0.5",
-    "ts-patch": "^3.1.2",
-    "typescript": "5.4.5",
+    "ts-patch": "^3.2.1",
+    "typescript": "^5.5.2",
     "typescript-transform-paths": "^3.4.7",
-    "typia": "^6.2.2"
+    "typia": "^6.3.1"
   },
@@ -42,0 +42,0 @@ "files": [

README.md

@@ -18,3 +18,3 @@ # `@samchon/openapi`
 
-Also, `@samchon/openapi` provides emended OpenAPI v3.1 definition and its converter/inverter from above versions for convenient development. The keyword "emended" means that [`OpenApi`](https://github.com/samchon/openapi/blob/master/src/OpenApi.ts) is not a direct OpenAPI v3.1 specification (OpenApiV3_1), but a little bit shrinked to remove ambiguous and duplicated expressions of OpenAPI v3.1 for the convenience of typia and nestia
+Also, `@samchon/openapi` provides emended OpenAPI v3.1 definition and its converter/inverter from above versions for convenient development. The keyword "emended" means that [`OpenApi`](https://github.com/samchon/openapi/blob/master/src/OpenApi.ts) is not a direct OpenAPI v3.1 specification ([`OpenApiV3_1`](https://github.com/samchon/openapi/blob/master/src/OpenApiV3_1.ts)), but a little bit shrinked to remove ambiguous and duplicated expressions of OpenAPI v3.1 for the convenience of `typia` and `nestia`.
 
@@ -41,4 +41,7 @@ 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.
 
+Additionally, `@samchon/openapi` provides [`IMigrateDocument`](https://github.com/samchon/openapi/blob/master/src/IMigrateDocument.ts) for OpenAPI generators.
 
 
+
+
 ## How to use
@@ -76,6 +79,4 @@ ```bash
 
-// also supports openapi generator libraries
-const migrate: IMigrateDocument = OpenApi.migrate(
-  OpenApi.convert(input),
-);
+// also helps openapi generator libraries
+const migrate: IMigrateDocument = OpenApi.migrate(output);
 ```
@@ -82,0 +83,0 @@

src/IMigrateDocument.ts

 import { IMigrateRoute } from "./IMigrateRoute";
 import { OpenApi } from "./OpenApi";
 
+/**
+ * Document of migration.
+ *
+ * The `IMigrateDocument` interface is a document of migration from
+ * {@link OpenAPI.IDocument OpenAPI document} to RPC (Remote Procedure Call)
+ * functions; {@link IMigrateRoute}.
+ *
+ * As the `IMigrateDocument` and {@link IMigrateRoute} have a lot of special
+ * stories, when you're developing OpenAPI generator library, please read
+ * their descriptions carefully including the description of properties.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export interface IMigrateDocument {
+  /**
+   * List of routes for migration.
+   */
   routes: IMigrateRoute[];
+
+  /**
+   * List of errors occurred during the migration.
+   */
   errors: IMigrateDocument.IError[];
 }
 export namespace IMigrateDocument {
+  /**
+   * Error of migration in the operation level.
+   */
   export interface IError {
+    /**
+     * Target operation causing the error.
+     */
     operation: () => OpenApi.IOperation;
+
+    /**
+     * Method of the operation.
+     *
+     * If the {@link OpenApi.IOperation.method} is not one of below type
+     * values, the operation would be ignored in the migration process for
+     * the RPC (Remote Procedure Call) function.
+     */
     method: "head" | "get" | "post" | "put" | "patch" | "delete";
+
+    /**
+     * Original path from the OpenAPI document.
+     */
     path: string;
+
+    /**
+     * List of error messages (reasons).
+     */
     messages: string[];
   }
 }

src/IMigrateRoute.ts

 import { OpenApi } from "./OpenApi";
 
+/**
+ * Route information for migration.
+ *
+ * The `IMigrateRoute` is a structure representing a route information for
+ * OpenAPI generated RPC (Remote Procedure Call) function composed from the
+ * {@link OpenApi.IOperation OpenAPI operation}.
+ *
+ * As the `IMigrateRoute` has a lot of speical stories, when you're developing
+ * OpenAPI generator library, please read its description carefully including
+ * the description of its properties.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
 export interface IMigrateRoute {
+  /**
+   * Method of the route.
+   *
+   * If the {@link OpenApi.IOperation.method} is not one of below type
+   * values, the operation would be ignored in the migration process for
+   * the RPC (Remote Procedure Call) function.
+   */
   method: "head" | "get" | "post" | "put" | "patch" | "delete";
+
+  /**
+   * Original path from the OpenAPI document.
+   */
   path: string;
+
+  /**
+   * Emended path for OpenAPI generator libraries.
+   *
+   * The difference between {@link path} is:
+   *
+   * 1. Path parameters are replaced with `:param` format.
+   * 2. Empty sub-paths are removed.
+   * 3. Do not starts with `/`.
+   */
   emendedPath: string;
-  accessor: string[]; // function accessor
-  parameters: IMigrateRoute.IParameter[]; // path parameters
-  headers: IMigrateRoute.IHeaders | null; // as an object
-  query: IMigrateRoute.IQuery | null; // as an object
-  body: IMigrateRoute.IBody | null; // request body
-  success: IMigrateRoute.IBody | null; // 200 or 201 status case
-  exceptions: Record<string, IMigrateRoute.IException>; // other status cases
+
+  /**
+   * Accessor for the route.
+   *
+   * The `accessor` is a list of string values that are representing how to
+   * access to the OpenAPI generated RPC (Remote Procedure Call) function
+   * through namespace(s).
+   *
+   * The `accessor` is composed with the following rules. At first, namespaces
+   * are composed by static directory names in the {@link path}. Parametric
+   * symbols represented by `:param` or `{param}` cannot be a part of the
+   * namespace.
+   *
+   * Instead, they would be a part of the function name. The function
+   * name is composed with the {@link method HTTP method} and parametric symbols
+   * like `getByParam` or `postByParam`. If there are multiple path parameters,
+   * they would be concatenated by `And` like `getByParam1AndParam2`.
+   *
+   * For refefence, if the {@link operation}'s {@link method} is `delete`, the
+   * function name would be replaced to `erase` instead of `delete`. It is
+   * the reason why the `delete` is a reserved keyword in many programming
+   * languages.
+   *
+   * - Exxample 1
+   *   - path: `POST /shopping/sellers/sales`
+   *   - accessor: `shopping.sellers.sales.post`
+   * - Example 2
+   *   - endpoint: `GET /shoppings/sellers/sales/:saleId/reviews/:reviewId/comments/:id
+   *   - accessor: `shoppings.sellers.sales.reviews.getBySaleIdAndReviewIdAndCommentId`
+   */
+  accessor: string[];
+
+  /**
+   * List of path parameters.
+   */
+  parameters: IMigrateRoute.IParameter[];
+
+  /**
+   * Metadata of headers.
+   *
+   * The `headers` property is a metadata of HTTP request headers for RPC function,
+   * including the parameter variable name and schema.
+   *
+   * Also, its {@link IMigrateRoute.IHeaders.schema} is always object or reference
+   * to object. Even though the original {@link OpenApi.IOperation OpenAPI operation}'s
+   * headers are separated to atomic typed properties, the `headers` property forcibly
+   * combines them into a single object type.
+   *
+   * For reference, if the `headers` property has been converted to an object type
+   * forcibly, its property {@link IMigrateRoute.IHeaders.name name} and
+   * {@link IMigrateRoute.IHeaders.key key} are always "headers".
+   */
+  headers: IMigrateRoute.IHeaders | null;
+
+  /**
+   * Metadata of query values.
+   *
+   * The `query` property is a metadata of HTTP request query values for RPC function,
+   * including the parameter variable name and schema.
+   *
+   * Also, its {@link IMigrateRoute.IQuery.schema} is always object or reference
+   * to object. Even though the original {@link OpenApi.IOperation OpenAPI operation}'s
+   * query parameters are separated to atomic typed properties, the `query` property
+   * forcibly combines them into a single object type.
+   *
+   * For reference, if the `query` property has been converted to an object type
+   * forcibly, its property {@link IMigrateRoute.IQuery.name name} and
+   * {@link IMigrateRoute.IQuery.key key} are always "headers".
+   */
+  query: IMigrateRoute.IQuery | null;
+
+  /**
+   * Metadata of request body.
+   *
+   * The `body` property is a metadata of HTTP request body for RPC function,
+   * including the parameter variable name, content type, and schema.
+   *
+   * If the `body` property is `null`, it means the operation does not require
+   * the request body data.
+   */
+  body: IMigrateRoute.IBody | null;
+
+  /**
+   * Metadata of response body for success case.
+   *
+   * The `success` property is a metadata of HTTP response body for RPC function,
+   * including content type, and schema when status code is `200` or `201`.
+   *
+   * If the `success` property is `null`, it means the operation does not have
+   * the response body data. In other words, the RPC function would return `void`.
+   */
+  success: IMigrateRoute.IBody | null;
+
+  /**
+   * Metadata of response body for exceptional status cases.
+   *
+   * The `exceptions` property is a metadata of HTTP response body for RPC
+   * function, including content type, and schema when status code is not `200`
+   * or `201`.
+   *
+   * The key of the `exceptions` property is the status code. It may be a
+   * stringified number, but sometimes it could be a string like "default",
+   * because the OpenAPI document allows the status code to be a string.
+   */
+  exceptions: Record<string, IMigrateRoute.IException>;
+
+  /**
+   * Description comment for the route function.
+   *
+   * The `comment` is a function returning description comment for the
+   * RPC function of OpenAPI generated. The comment is composed with the
+   * following rules:
+   *
+   * 1. Starts from the {@link OpenApi.IOperation.summary} paragraph.
+   * 2. The next paragraphs are filled with {@link OpenApi.IOperation.description}.
+   * 3. Parameter descriptions are added with `@param` tag.
+   * 4. Security requirements are added with `@security` tag.
+   * 5. Tag names are added with `@tag` tag.
+   * 6. If {@link OpenApi.IOperation.deprecated}, `@deprecated` tag is added.
+   */
   comment: () => string;
+
+  /**
+   * Original operation from the OpenAPI document.
+   *
+   * The `operation` is a function returning the original
+   * {@link OpenApi.IOperation} from the {@link OpenAPI} document.
+   */
   operation: () => OpenApi.IOperation;
@@ -16,0 +170,0 @@ }

src/internal/MigrateConverter.ts

@@ -5,3 +5,3 @@ import { IMigrateRoute } from "../IMigrateRoute";
 import { StringUtil } from "../utils/StringUtil";
-import { MigrateOperationConverter } from "./MigrateOperationConverter";
+import { MigrateRouteConverter } from "./MigrateRouteConverter";
 import { MigrateRouteAccessor } from "./MigrateRouteAccessor";
@@ -22,3 +22,3 @@
             const migrated: IMigrateRoute | string[] =
-              MigrateOperationConverter.convert({
+              MigrateRouteConverter.convert({
                 document,
@@ -25,0 +25,0 @@ method,

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

311009

increased by4.87%

Lines of code

7678

increased by4.93%

Number of lines in readme file

87

increased by1.16%

No dependency changes