openapi-jsonrpc-jsdoc 1.4.3 → 1.5.1

package/README.md

@@ -17,15 +17,19 @@ npm i openapi-jsonrpc-jsdoc
  * @description Название API
  * @param {object} parameters - params
  * @param {string} parameters.id - id
+ * @param {string} [parameters.test] - test
+ * @param {string[]} parameters.array - array
+ * @param {1|2} parameters.num - enum
+ * @tags api
  * @example
  * {
- *    "@context": "https://www.w3.org/ns/activitystreams",
- *    "type": "Note"
+ *    "id": "https://www.w3.org/ns/activitystreams"
  * }
  */
 module.exports = (parameters) => {
-    return parameters.id;
-}
+  return parameters.id;
+};
+
 ```
 
 ### Generate OpenAPI JSON
@@ -39,6 +43,9 @@ openapiJSONRpcJSDoc({
             url: '0.0.0.0:8080',
          },
     ],
+    info: {
+      title: 'Test API',
+    },
     packageUrl: './package.json',
     files: './api/*.js',
 }).then(data => {
@@ -51,22 +58,16 @@ openapiJSONRpcJSDoc({
 
 ```json
 {
-  "x-send-defaults": true,
   "openapi": "3.1.0",
-  "x-api-id": "json-rpc-example",
-  "x-headers": [],
-  "x-explorer-enabled": true,
-  "x-proxy-enabled": true,
   "x-samples-enabled": true,
   "x-samples-languages": [
-    "curl",
     "node",
     "javascript"
   ],
   "info": {
-    "version": "1.0.4",
-    "title": "openapi-jsonrpc-jsdoc",
-    "description": "OpenAPI generator"
+    "version": "1.4.3",
+    "title": "Test API",
+    "description": "Transform JSDoc-annotated JSON-RPC 2.0 methods into OpenAPI specifications."
   },
   "servers": [
     {
@@ -81,7 +82,7 @@ openapiJSONRpcJSDoc({
         "summary": "/v1",
         "description": "Название API",
         "tags": [
-          "JSONRPC"
+          "api"
         ],
         "parameters": [],
         "responses": {
@@ -107,32 +108,31 @@ openapiJSONRpcJSDoc({
           }
         },
         "requestBody": {
+          "required": true,
           "content": {
             "application/json": {
               "schema": {
                 "type": "object",
                 "required": [
                   "method",
-                  "id",
-                  "jsonrpc",
-                  "params"
+                  "jsonrpc"
                 ],
                 "properties": {
                   "method": {
                     "type": "string",
-                    "default": "v1",
                     "description": "API method v1"
                   },
                   "id": {
-                    "type": "integer",
-                    "default": 1,
-                    "format": "int32",
+                    "type": [
+                      "string",
+                      "integer"
+                    ],
                     "description": "Request ID"
                   },
                   "jsonrpc": {
                     "type": "string",
                     "default": "2.0",
-                    "description": "JSON-RPC Version (2.0)"
+                    "description": "JSON-RPC 2.0 protocol"
                   },
                   "params": {
                     "title": "Parameters",
@@ -142,15 +142,33 @@ openapiJSONRpcJSDoc({
                       "type": "Note"
                     },
                     "required": [
-                      "method",
                       "id",
-                      "jsonrpc",
-                      "id"
+                      "array",
+                      "num"
                     ],
                     "properties": {
                       "id": {
                         "type": "string",
                         "description": "id"
+                      },
+                      "test": {
+                        "type": "string",
+                        "description": "test"
+                      },
+                      "array": {
+                        "type": "array",
+                        "description": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "num": {
+                        "enum": [
+                          1,
+                          2
+                        ],
+                        "type": "integer",
+                        "description": "enum"
                       }
                     }
                   }
@@ -160,83 +178,18 @@ openapiJSONRpcJSDoc({
           }
         }
       }
-    },
-    "/api/v2": {
-      "post": {
-        "operationId": "v2.js",
-        "deprecated": true,
-        "summary": "/v2",
-        "description": "Название API 2",
-        "tags": [
-          "JSONRPC"
-        ],
-        "parameters": [],
-        "responses": {
-          "200": {
-            "description": "OK",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object"
-                }
-              }
-            }
-          },
-          "default": {
-            "description": "unexpected error",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
-          }
-        },
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "required": [
-                  "method",
-                  "id",
-                  "jsonrpc"
-                ],
-                "properties": {
-                  "method": {
-                    "type": "string",
-                    "default": "v2",
-                    "description": "API method v2"
-                  },
-                  "id": {
-                    "type": "integer",
-                    "default": 1,
-                    "format": "int32",
-                    "description": "Request ID"
-                  },
-                  "jsonrpc": {
-                    "type": "string",
-                    "default": "2.0",
-                    "description": "JSON-RPC Version (2.0)"
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
     }
   },
   "components": {
     "securitySchemes": {
       "BasicAuth": {
         "type": "http",
-        "scheme": "digest"
+        "scheme": "basic"
       }
     },
     "schemas": {
       "Error": {
+        "type": "object",
         "required": [
           "error",
           "id",
@@ -244,14 +197,17 @@ openapiJSONRpcJSDoc({
         ],
         "properties": {
           "id": {
-            "type": "integer",
-            "format": "int32"
+            "type": [
+              "string",
+              "integer"
+            ]
           },
           "error": {
             "type": "object"
           },
           "jsonrpc": {
-            "type": "string"
+            "type": "string",
+            "default": "2.0"
           }
         }
       }

package/index.mjs

@@ -20,6 +20,15 @@ function extractTypeName(names = []) {
   return typeName;
 }
 
+function isBigInt64(n) {
+  try {
+    const b = BigInt(n);
+    return b >= -9223372036854775808n && b <= 9223372036854775807n;
+  } catch {
+    return false;
+  }
+}
+
 function resolveSchemaFromTypeNames(names) {
   let type;
   let format;
@@ -73,20 +82,29 @@ function resolveSchemaFromTypeNames(names) {
       enumData = enumData.map((n) => {
         if (!Number.isNaN(Number(n))) {
           return Number(n);
+        } else if (isBigInt64(n)) {
+          return n;
         }
-        return n;
+        return String(n);
       });
 
-      if (enumData.every(n => Number.isInteger(Number(n)))) {
+      if (enumData.every(n => Number.isSafeInteger(n))) {
         type = 'integer';
+      } else if (enumData.every(n => Number.isInteger(n))) {
+        type = 'number';
+        format = 'float';
+      } else if (enumData.every(n => typeof n === 'number' && n === Math.fround(n))) {
+        type = 'number';
+        format = 'double';
+      } else  if (enumData.every(n => isBigInt64(n))) {
+        type = 'integer';
+        format = 'int64';
       } else if (enumData.every(n => !Number.isNaN(Number(n)))) {
         type = 'number';
       } else if (enumData.every(n => n?.toLowerCase() === 'boolean')) {
         type = 'boolean';
       } else if (enumData.every(n => n?.toLowerCase() === 'number')) {
         type = 'number';
-      } else if (enumData.every(n => n?.toLowerCase() === 'string')) {
-        type = 'string';
       } else if (enumData.every(n => n?.toLowerCase() === 'date')) {
         type = 'string';
         format = 'date-time';
@@ -99,8 +117,13 @@ function resolveSchemaFromTypeNames(names) {
       } else if (enumData.every(n => n?.toLowerCase() === 'false')) {
         type = 'boolean';
         constant = false;
-      } else {
+      } else if (enumData.every(n => typeof n === 'string')) {
         type = 'string';
+      } else if (enumData.length === 1) {
+        type = enumData[0];
+        constant = true;
+      } else {
+        type = undefined;
       }
 
       if (enumData?.length === 1) {
@@ -108,6 +131,8 @@ function resolveSchemaFromTypeNames(names) {
           [format] = enumData;
         }
         enumData = undefined;
+      } else if (nullable) {
+        enumData.push(null);
       }
       break;
     }
@@ -128,44 +153,58 @@ function resolveSchemaFromTypeNames(names) {
 
 export default async function openapiJsonrpcJsdoc({
   openapi = '3.1.0',
+  encoding = 'utf8',
+  access = 'public',
   files,
+  info = {},
   securitySchemes = {},
   packageUrl,
   servers,
   api = '/',
+  samples = ['node', 'javascript'],
+  ...xHeaders
 }) {
-  const allData = await jsdoc.explain({
+  const options = {
+    access,
+    encoding,
+    samples,
     files: Array.isArray(files) ? files : [files],
-    package: packageUrl,
-    access: 'public',
-    encoding: 'utf8',
     undocumented: false,
     allowUnknownTags: true,
     dictionaries: ['jsdoc'],
-    cache: true,
-  });
-  const package_ = allData.find(item => item.kind === 'package');
-  const documents = allData.filter(item => item.kind !== 'package');
+  };
+  if (info.title) {
+    options.cache = true;
+  } else {
+    options.package = packageUrl;
+  }
+  let documents;
+  if (options.cache) {
+    documents = await jsdoc.explain(options);
+  } else {
+    const allData = await jsdoc.explain(options);
+    documents = allData.filter(item => item.kind !== 'package');
+    const package_ = allData.find(item => item.kind === 'package');
+    info.version = package_.version;
+    info.title = package_.name;
+    info.description = package_.description;
+  }
+  if (!info.title) {
+    throw new Error('API title is required. Please set packageUrl or info object.');
+  }
   const temporaryDocument = {
     'openapi': openapi,
-    'x-send-defaults': true,
-    'x-api-id': 'json-rpc-example',
-    'x-headers': [],
-    'x-explorer-enabled': true,
-    'x-proxy-enabled': true,
-    'x-samples-enabled': true,
-    'x-samples-languages': ['node', 'javascript'],
-    'info': {
-      version: package_.version,
-      title: package_.name,
-      description: package_.description,
-    },
+    'x-samples-enabled': samples.length > 0,
+    'x-samples-languages': samples,
+    ...xHeaders,
+    'info': info,
     'servers': servers,
     'paths': {},
     'components': {
       securitySchemes,
       schemas: {
         Error: {
+          type: 'object',
           required: [
             'error',
             'id',
@@ -173,14 +212,14 @@ export default async function openapiJsonrpcJsdoc({
           ],
           properties: {
             id: {
-              type: 'integer',
-              format: 'int32',
+              type: ['string', 'integer'],
             },
             error: {
               type: 'object',
             },
             jsonrpc: {
               type: 'string',
+              default: '2.0',
             },
           },
         },
@@ -249,11 +288,10 @@ export default async function openapiJsonrpcJsdoc({
                 properties: {
                   method: {
                     type: 'string',
-                    default: apiName,
                     description: `API method ${apiName}`,
                   },
                   id: {
-                    type: ['string'],
+                    type: ['string', 'integer'],
                     description: 'Request ID',
                   },
                   jsonrpc: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-jsonrpc-jsdoc",
-  "version": "1.4.3",
+  "version": "1.5.1",
   "description": "Transform JSDoc-annotated JSON-RPC 2.0 methods into OpenAPI specifications.",
   "main": "index.mjs",
   "type": "module",