@samchon/openapi - npm Package Compare versions

Comparing version 0.1.4 to 0.1.5

lib/internal/OpenApiV3_1Converter.js

@@ -8,3 +8,5 @@ "use strict";
         var _a;
-        return (Object.assign(Object.assign({}, input), { components: convertComponents((_a = input.components) !== null && _a !== void 0 ? _a : {}), paths: input.paths
+        if (input["x-samchon-emended"] === true)
+            return input;
+        return Object.assign(Object.assign({}, input), { components: convertComponents((_a = input.components) !== null && _a !== void 0 ? _a : {}), paths: input.paths
                 ? Object.fromEntries(Object.entries(input.paths)
@@ -18,3 +20,3 @@ .filter(([_, v]) => v !== undefined)
                     .filter(([_, value]) => value !== undefined))
-                : undefined }));
+                : undefined, "x-samchon-emended": true });
     };
@@ -21,0 +23,0 @@ /* -----------------------------------------------------------

lib/OpenApi.d.ts

@@ -17,5 +17,5 @@ import { OpenApiV3 } from "./OpenApiV3";
  *
- * 1. `type: ["string", "null"]`
- * 2. `type: "string", nullable: true`
- * 3. `oneOf: [{ type: "string" }, { type: "null" }]`
+ * 1. `{ type: ["string", "null"] }`
+ * 2. `{ type: "string", nullable: true }`
+ * 3. `{ oneOf: [{ type: "string" }, { type: "null" }] }`
  *
@@ -55,2 +55,3 @@ * Here is the entire list of differences between OpenAPI v3.1 and emended `OpenApi`.
         tags?: IDocument.ITag[];
+        "x-samchon-emended"?: boolean;
     }
@@ -57,0 +58,0 @@ namespace IDocument {

lib/OpenApi.js

@@ -23,5 +23,5 @@ "use strict";
  *
- * 1. `type: ["string", "null"]`
- * 2. `type: "string", nullable: true`
- * 3. `oneOf: [{ type: "string" }, { type: "null" }]`
+ * 1. `{ type: ["string", "null"] }`
+ * 2. `{ type: "string", nullable: true }`
+ * 3. `{ oneOf: [{ type: "string" }, { type: "null" }] }`
  *
@@ -28,0 +28,0 @@ * Here is the entire list of differences between OpenAPI v3.1 and emended `OpenApi`.

lib/OpenApiV3_1.d.ts

@@ -21,2 +21,3 @@ /**
         tags?: IDocument.ITag[];
+        "x-samchon-emended"?: boolean;
     }
@@ -23,0 +24,0 @@ namespace IDocument {

package.json

 {
   "name": "@samchon/openapi",
-  "version": "0.1.4",
-  "description": "",
+  "version": "0.1.5",
+  "description": "OpenAPI definitions and converters for 'typia' and 'nestia'.",
   "main": "./lib/index.js",
@@ -15,5 +15,18 @@ "typings": "./lib/index.d.ts",
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
+  "keywords": [
+    "swagger",
+    "openapi",
+    "typia",
+    "nestia"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/samchon/openapi"
+  },
+  "author": "Jeongho Nam",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/samchon/openapi/issues"
+  },
+  "homepage": "https://github.com/samchon/openapi",
   "devDependencies": {
@@ -20,0 +33,0 @@ "@types/node": "^20.12.7",

README.md

@@ -0,1 +1,5 @@
+# `@samchon/openapi`
+
+![Nestia Editor](https://github.com/samchon/openapi/assets/13158709/350128f7-c159-4ba4-8f8c-743908ada8eb)
+
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/openapi/blob/master/LICENSE)
@@ -6,2 +10,56 @@ [![npm version](https://img.shields.io/npm/v/@samchon/openapi.svg)](https://www.npmjs.com/package/@samchon/openapi)
 
-OpenAPI definitions and converters for [typia](https://github.com/samchon/typia) and [nestia](https://github.com/samchon/nestia).
+OpenAPI definitions and converters for [typia](https://github.com/samchon/typia) and [nestia](https://github.com/samchon/nestia).
+
+`@samchon/openapi` is a collection of OpenAPI definitions of below versions. Those type definitions does not contain every properties of OpenAPI specification, but just have only some features essentially required for `typia` and `nestia` (especially [`@nestia/editor`](https://nestia.io/docs/editor/)).
+
+  1. [Swagger v2.0](https://github.com/samchon/openapi/blob/master/src/SwaggerV2.ts)
+  2. [OpenAPI v3.0](https://github.com/samchon/openapi/blob/master/src/OpenApiV3.ts)
+  3. [OpenAPI v3.1](https://github.com/samchon/openapi/blob/master/src/OpenApiV3_1.ts)
+
+Also, `@samchon/openapi` provides emended OpenAPI v3.1 definition and its converter 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
+
+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" }] }`
+
+Here is the entire list of differences between OpenAPI v3.1 and emended OpenApi.
+
+  - Operation
+    - Merged `OpenApiV3_1.IPathItem.parameters` to `OpenApi.IOperation.parameters`
+    - Resolved references of `OpenApiV3_1.IOperation` mebers
+  - JSON Schema
+    - Decomposed mixed type: `OpenApiV3_1.IJsonSchema.IMixed`
+    - Resolved nullable property: `OpenApiV3_1.IJsonSchema.__ISignificant.nullable`
+    - Array type utilizes only single `OpenAPI.IJsonSchema.IArray.items`
+    - Tuple type utilizes only `OpenApi.IJsonSchema.ITuple.prefixItems`
+    - Merged `OpenApiV3_1.IJsonSchema.IAnyOf` to `OpenApi.IJsonSchema.IOneOf`
+    - Merged `OpenApiV3_1.IJsonSchema.IRecursiveReference` to `OpenApi.IJsonSchema.IReference`
+
+
+
+## How to use
+```bash
+npm install @samchon/openapi
+```
+
+```typescript
+import { OpenApi, SwaggerV2, OpenApiV3, OpenApiV3_1 } from "@samchon/openapi";
+
+// original Swagger/OpenAPI document
+const input: 
+  | SwaggerV2.IDocument
+  | OpenApiV3.IDocument
+  | OpenApiV3_1.IDocument = { ... };
+
+// you can convert it to emended OpenAPI v3.1
+const output: OpenApi.IDocument = OpenApi.convert(input);
+```
+
+
+
+## Related Projects
+  - `typia`: https://github.com/samchon/typia
+  - `nestia`: https://github.com/samchon/nestia
+  - `@nestia/editor`: https://nestia.io/docs/editor

src/internal/OpenApiV3_1Converter.ts

@@ -5,25 +5,30 @@ import { OpenApi } from "../OpenApi";
 export namespace OpenApiV3_1Converter {
-  export const convert = (input: OpenApiV3_1.IDocument): OpenApi.IDocument => ({
-    ...input,
-    components: convertComponents(input.components ?? {}),
-    paths: input.paths
-      ? Object.fromEntries(
-          Object.entries(input.paths)
-            .filter(([_, v]) => v !== undefined)
-            .map(
-              ([key, value]) => [key, convertPathItem(input)(value)] as const,
-            ),
-        )
-      : undefined,
-    webhooks: input.webhooks
-      ? Object.fromEntries(
-          Object.entries(input.webhooks)
-            .filter(([_, v]) => v !== undefined)
-            .map(
-              ([key, value]) => [key, convertWebhooks(input)(value)!] as const,
-            )
-            .filter(([_, value]) => value !== undefined),
-        )
-      : undefined,
-  });
+  export const convert = (input: OpenApiV3_1.IDocument): OpenApi.IDocument => {
+    if (input["x-samchon-emended"] === true) return input as OpenApi.IDocument;
+    return {
+      ...input,
+      components: convertComponents(input.components ?? {}),
+      paths: input.paths
+        ? Object.fromEntries(
+            Object.entries(input.paths)
+              .filter(([_, v]) => v !== undefined)
+              .map(
+                ([key, value]) => [key, convertPathItem(input)(value)] as const,
+              ),
+          )
+        : undefined,
+      webhooks: input.webhooks
+        ? Object.fromEntries(
+            Object.entries(input.webhooks)
+              .filter(([_, v]) => v !== undefined)
+              .map(
+                ([key, value]) =>
+                  [key, convertWebhooks(input)(value)!] as const,
+              )
+              .filter(([_, value]) => value !== undefined),
+          )
+        : undefined,
+      "x-samchon-emended": true,
+    };
+  };
 
@@ -30,0 +35,0 @@ /* -----------------------------------------------------------

src/OpenApi.ts

@@ -21,5 +21,5 @@ import { OpenApiV3 } from "./OpenApiV3";
  *
- * 1. `type: ["string", "null"]`
- * 2. `type: "string", nullable: true`
- * 3. `oneOf: [{ type: "string" }, { type: "null" }]`
+ * 1. `{ type: ["string", "null"] }`
+ * 2. `{ type: "string", nullable: true }`
+ * 3. `{ oneOf: [{ type: "string" }, { type: "null" }] }`
  *
@@ -82,2 +82,3 @@ * Here is the entire list of differences between OpenAPI v3.1 and emended `OpenApi`.
     tags?: IDocument.ITag[];
+    "x-samchon-emended"?: boolean;
   }
@@ -84,0 +85,0 @@ export namespace IDocument {

src/OpenApiV3_1.ts

@@ -41,2 +41,3 @@ /**
     tags?: IDocument.ITag[];
+    "x-samchon-emended"?: boolean;
   }
@@ -43,0 +44,0 @@ export namespace IDocument {

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

Mixed license

License

(Experimental) Package contains multiple licenses.

Found 1 instance in 1 package

No contributors or author data

Maintenance

Package does not specify a list of contributors or an author in package.json.

Found 1 instance in 1 package

No bug tracker

Maintenance

Package does not have a linked bug tracker in package.json.

Found 1 instance in 1 package

No repository

Supply chain risk

Package does not have a linked source code repository. Without this field, a package will have no reference to the location of the source code use to generate the package.

Found 1 instance in 1 package

No website

Quality

Package does not have a website.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

167309

increased by2.26%

Number of low license alerts

0

decreased by-100%

Lines of code

4233

increased by0.26%

Number of low maintenance alerts

0

decreased by-100%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

64

increased by966.67%

Number of low supply chain risk alerts

0

decreased by-100%

No dependency changes