openapi-jsonrpc-jsdoc 1.4.1 → 1.4.3

package/README.md

@@ -8,7 +8,7 @@ npm i openapi-jsonrpc-jsdoc
 
 ## Examples
 
-### Create JSON-RPC Method
+### Usage Example
 
 ```js
 // api/api-v1.js
@@ -28,11 +28,9 @@ module.exports = (parameters) => {
 }
 ```
 
-### Run package
+### Generate OpenAPI JSON
 
 ```js
-// index.js
-const fs = require('fs');
 const openapiJSONRpcJSDoc = require('openapi-jsonrpc-jsdoc');
 openapiJSONRpcJSDoc({
     api: '/',
@@ -44,7 +42,7 @@ openapiJSONRpcJSDoc({
     packageUrl: './package.json',
     files: './api/*.js',
 }).then(data => {
-  fs.writeFileSync('openapi.json', JSON.stringify(data, null, 2));  
+  JSON.stringify(data, null, 2);// openapi.json
 });
 ```
 
@@ -54,7 +52,7 @@ openapiJSONRpcJSDoc({
 ```json
 {
   "x-send-defaults": true,
-  "openapi": "3.0.0",
+  "openapi": "3.1.0",
   "x-api-id": "json-rpc-example",
   "x-headers": [],
   "x-explorer-enabled": true,

package/index.mjs

@@ -1,6 +1,139 @@
 import jsdoc from 'jsdoc-api';
 
-export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, servers, api = '/' }) {
+function extractName(name) {
+  try {
+    return name.match(/\.(.+)/i)[1]; //eslint-disable-line
+  } catch {
+    return 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 resolveSchemaFromTypeNames(names) {
+  let type;
+  let format;
+  let items;
+  let nullable;
+  let constant;
+  let enumData;
+
+  switch (extractTypeName(names)) {
+    case 'Array.<string>': {
+      type = 'array';
+      items = {type: 'string'};
+      break;
+    }
+    case 'Array.<number>': {
+      type = 'array';
+      items = {type: 'number'};
+      break;
+    }
+    case 'URL': {
+      type = 'string';
+      format = 'url';
+      break;
+    }
+    case 'String':
+    case 'string': {
+      type = 'string';
+      break;
+    }
+    case 'Number':
+    case 'number': {
+      type = 'number';
+      break;
+    }
+    case 'Boolean':
+    case 'boolean': {
+      type = 'boolean';
+      break;
+    }
+    case 'Date': {
+      type = 'string';
+      format = 'date-time';
+      break;
+    }
+    case 'enum': {
+      enumData = names;
+      if (enumData.includes('null')) {
+        nullable = true;
+        enumData = enumData.filter(n => n !== 'null');
+      }
+      enumData = enumData.map((n) => {
+        if (!Number.isNaN(Number(n))) {
+          return Number(n);
+        }
+        return n;
+      });
+
+      if (enumData.every(n => Number.isInteger(Number(n)))) {
+        type = 'integer';
+      } 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';
+      } else if (enumData.every(n => n === 'URL')) {
+        type = 'string';
+        format = 'url';
+      } else if (enumData.every(n => n?.toLowerCase() === 'true')) {
+        type = 'boolean';
+        constant = true;
+      } else if (enumData.every(n => n?.toLowerCase() === 'false')) {
+        type = 'boolean';
+        constant = false;
+      } else {
+        type = 'string';
+      }
+
+      if (enumData?.length === 1) {
+        if (!format) {
+          [format] = enumData;
+        }
+        enumData = undefined;
+      }
+      break;
+    }
+    default: {
+      break;
+    }
+  }
+
+  return {
+    type,
+    format,
+    nullable,
+    items,
+    constant,
+    enumData,
+  };
+}
+
+export default async function openapiJsonrpcJsdoc({
+  openapi = '3.1.0',
+  files,
+  securitySchemes = {},
+  packageUrl,
+  servers,
+  api = '/',
+}) {
   const allData = await jsdoc.explain({
     files: Array.isArray(files) ? files : [files],
     package: packageUrl,
@@ -9,12 +142,13 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
     undocumented: false,
     allowUnknownTags: true,
     dictionaries: ['jsdoc'],
+    cache: true,
   });
   const package_ = allData.find(item => item.kind === 'package');
   const documents = allData.filter(item => item.kind !== 'package');
   const temporaryDocument = {
+    'openapi': openapi,
     'x-send-defaults': true,
-    'openapi': '3.0.0',
     'x-api-id': 'json-rpc-example',
     'x-headers': [],
     'x-explorer-enabled': true,
@@ -52,11 +186,7 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
         },
       }
     },
-    'security': [
-      {
-        BasicAuth: [],
-      },
-    ],
+    'security': Object.keys(securitySchemes).map(val => ({ [val]: [] })),
     'tags': [],
   };
   const requiredSchema = ['method', 'jsonrpc'];
@@ -110,6 +240,7 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
           }
         },
         requestBody: {
+          required: true,
           content: {
             'application/json': {
               schema: {
@@ -122,9 +253,7 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
                     description: `API method ${apiName}`,
                   },
                   id: {
-                    type: 'integer',
-                    default: 1,
-                    format: 'int32',
+                    type: ['string'],
                     description: 'Request ID',
                   },
                   jsonrpc: {
@@ -157,61 +286,38 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
           if (parameter.type.names[0] === 'object') {
             return accumulator;
           }
-          let type;
-          if (parameter.type.names.length === 0) {
-            type = 'null';
-          } else if (parameter.type.names.length === 1) {
-            type = parameter.type.names[0];
-          } else {
-            type = 'enum';
-          }
-          let items;
-          let enumData;
-          let oneOf;
 
-          switch (type) {
-            case 'Array.<string>': {
-              type = 'array';
-              items = { type: 'string' };
-              break;
-            }
-            case 'Array.<number>': {
-              type = 'array';
-              items = { type: 'number' };
-              break;
-            }
-            case 'enum': {
-              enumData = parameter.type.names;
-              oneOf = parameter.type.names.map((n) => {
-                if (!Number.isNaN(Number(n))) {
-                  return Number(n);
-                }
-                return n;
-              });
-              if (parameter.type.names.every(n => Number.isInteger(Number(n)))) {
-                type = 'integer';
-              } else if (parameter.type.names.every(n => !Number.isNaN(Number(n)))) {
-                type = 'number';
-              } else {
-                type = 'string';
-              }
-              break;
-            }
-            default: {
-              break;
-            }
-          }
+          const name = extractName(parameter.name);
+          accumulator.properties[name] = accumulator.properties[name] ?? {};
           const description = parameter.description;
-          let name;
-          try {
-            name = parameter.name.match(/\.(.+)/i)[1]; //eslint-disable-line
-          } catch {
-            name = parameter.name;
-          }
+          const defaultValue = parameter.defaultvalue;
+
+          const {
+            items,
+            constant,
+            enumData,
+            type,
+            format,
+            nullable,
+          } = resolveSchemaFromTypeNames(parameter.type.names)
           if (!parameter.optional) {
             accumulator.required.push(name);
           }
-          accumulator.properties[name] = accumulator.properties[name] ?? {};
+          if (nullable) {
+            accumulator.properties[name].nullable = nullable;
+          }
+          if (defaultValue) {
+            accumulator.properties[name].default = defaultValue;
+          }
+          if (constant) {
+            accumulator.properties[name].const = constant;
+          }
+          if (format) {
+            accumulator.properties[name].format = format;
+          }
+          if (enumData) {
+            accumulator.properties[name].enum = enumData;
+          }
           if (type) {
             accumulator.properties[name].type = type;
           }
@@ -221,13 +327,6 @@ export default async function openapiJsonrpcJsdoc({ files, securitySchemes = {},
           if (items) {
             accumulator.properties[name].items = items;
           }
-          if (enumData) {
-            accumulator.properties[name].enum = enumData;
-          }
-          if (oneOf) {
-            accumulator.properties[name].oneOf = oneOf;
-          }
-
           return accumulator;
         },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-jsonrpc-jsdoc",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "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"