openapi-jsonrpc-jsdoc 1.4.2 → 1.5.0

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.0.0",
-  "x-api-id": "json-rpc-example",
-  "x-headers": [],
-  "x-explorer-enabled": true,
-  "x-proxy-enabled": true,
+  "openapi": "3.1.0",
   "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

@@ -8,24 +8,36 @@ function extractName(name) {
   }
 }
 
+function extractTypeName(names = []) {
+  let typeName;
+  if (names.length === 0) {
+    typeName = 'null';
+  } else if (names.length === 1) {
+    [typeName] = names;
+  } else {
+    typeName = 'enum';
+  }
+  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;
   let items;
-  let oneOf;
   let nullable;
   let constant;
   let enumData;
 
-  if (names.length === 0) {
-    type = 'null';
-  } else if (names.length === 1) {
-    [type] = names;
-  } else {
-    type = 'enum';
-  }
-
-  switch (type) {
+  switch (extractTypeName(names)) {
     case 'Array.<string>': {
       type = 'array';
       items = {type: 'string'};
@@ -67,23 +79,32 @@ function resolveSchemaFromTypeNames(names) {
         nullable = true;
         enumData = enumData.filter(n => n !== 'null');
       }
-      oneOf = enumData.map((n) => {
+      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';
@@ -96,18 +117,22 @@ 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 && oneOf?.length === 1) {
-        if (enumData[0] === oneOf[0]) {
-          if (!format) {
-            [format] = enumData;
-          }
-          oneOf = undefined;
-          enumData = undefined;
+      if (enumData?.length === 1) {
+        if (!format) {
+          [format] = enumData;
         }
+        enumData = undefined;
+      } else if (nullable) {
+        enumData.push(null);
       }
       break;
     }
@@ -119,7 +144,6 @@ function resolveSchemaFromTypeNames(names) {
   return {
     type,
     format,
-    oneOf,
     nullable,
     items,
     constant,
@@ -127,31 +151,42 @@ function resolveSchemaFromTypeNames(names) {
   };
 }
 
-export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, servers, api = '/' }) {
+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({
     files: Array.isArray(files) ? files : [files],
-    package: packageUrl,
-    access: 'public',
-    encoding: 'utf8',
+    packageJson: packageUrl,
+    access,
+    encoding,
     undocumented: false,
     allowUnknownTags: true,
     dictionaries: ['jsdoc'],
+    cache: true,
+    samples,
   });
   const package_ = allData.find(item => item.kind === 'package');
   const documents = allData.filter(item => item.kind !== 'package');
   const temporaryDocument = {
-    'x-send-defaults': true,
-    'openapi': '3.0.0',
-    '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'],
+    'openapi': openapi,
+    'x-samples-enabled': samples.length > 0,
+    'x-samples-languages': samples,
+    ...xHeaders,
     'info': {
       version: package_.version,
       title: package_.name,
       description: package_.description,
+      ...info,
     },
     'servers': servers,
     'paths': {},
@@ -159,6 +194,7 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
       securitySchemes,
       schemas: {
         Error: {
+          type: 'object',
           required: [
             'error',
             'id',
@@ -166,26 +202,25 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
           ],
           properties: {
             id: {
-              type: 'integer',
-              format: 'int32',
+              type: ['string', 'integer'],
             },
             error: {
               type: 'object',
             },
             jsonrpc: {
               type: 'string',
+              default: '2.0',
             },
           },
         },
       }
     },
-    'security': [
-      {
-        BasicAuth: [],
-      },
-    ],
+    'security': Object.keys(securitySchemes).map(val => ({ [val]: [] })),
     'tags': [],
   };
+  if (!temporaryDocument.info.title) {
+    throw new Error('Info title is required');
+  }
   const requiredSchema = ['method', 'jsonrpc'];
   prepare: for (const module of documents) {
     let isJsonRpc = false;
@@ -237,6 +272,7 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
           }
         },
         requestBody: {
+          required: true,
           content: {
             'application/json': {
               schema: {
@@ -245,13 +281,10 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
                 properties: {
                   method: {
                     type: 'string',
-                    default: apiName,
                     description: `API method ${apiName}`,
                   },
                   id: {
-                    type: 'integer',
-                    default: 1,
-                    format: 'int32',
+                    type: ['string', 'integer'],
                     description: 'Request ID',
                   },
                   jsonrpc: {
@@ -285,9 +318,10 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
             return accumulator;
           }
 
-          const description = parameter.description;
           const name = extractName(parameter.name);
           accumulator.properties[name] = accumulator.properties[name] ?? {};
+          const description = parameter.description;
+          const defaultValue = parameter.defaultvalue;
 
           const {
             items,
@@ -295,7 +329,6 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
             enumData,
             type,
             format,
-            oneOf,
             nullable,
           } = resolveSchemaFromTypeNames(parameter.type.names)
           if (!parameter.optional) {
@@ -304,6 +337,9 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
           if (nullable) {
             accumulator.properties[name].nullable = nullable;
           }
+          if (defaultValue) {
+            accumulator.properties[name].default = defaultValue;
+          }
           if (constant) {
             accumulator.properties[name].const = constant;
           }
@@ -313,9 +349,6 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
           if (enumData) {
             accumulator.properties[name].enum = enumData;
           }
-          if (oneOf) {
-            accumulator.properties[name].oneOf = oneOf;
-          }
           if (type) {
             accumulator.properties[name].type = type;
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-jsonrpc-jsdoc",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Transform JSDoc-annotated JSON-RPC 2.0 methods into OpenAPI specifications.",
   "main": "index.mjs",
   "type": "module",
@@ -33,8 +33,7 @@
   },
   "devDependencies": {
     "ava": "~6.4.1",
-    "express": "~5.2.1",
-    "express-openapi-validator": "~5.6.2"
+    "express": "~5.2.1"
   },
   "engines": {
     "node": ">= 22"