openapi-jsonrpc-jsdoc 1.5.0 → 1.5.2

package/index.mjs

@@ -43,6 +43,14 @@ function resolveSchemaFromTypeNames(names) {
       items = {type: 'string'};
       break;
     }
+    case 'Array.<bigint>': {
+      type = 'array';
+      items = {
+        type: 'integer',
+        format: 'int64',
+      };
+      break;
+    }
     case 'Array.<number>': {
       type = 'array';
       items = {type: 'number'};
@@ -164,30 +172,40 @@ export default async function openapiJsonrpcJsdoc({
   samples = ['node', 'javascript'],
   ...xHeaders
 }) {
-  const allData = await jsdoc.explain({
-    files: Array.isArray(files) ? files : [files],
-    packageJson: packageUrl,
+  const options = {
     access,
     encoding,
+    samples,
+    files: Array.isArray(files) ? files : [files],
     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');
+  };
+  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-samples-enabled': samples.length > 0,
     'x-samples-languages': samples,
     ...xHeaders,
-    'info': {
-      version: package_.version,
-      title: package_.name,
-      description: package_.description,
-      ...info,
-    },
+    'info': info,
     'servers': servers,
     'paths': {},
     'components': {
@@ -218,9 +236,6 @@ export default async function openapiJsonrpcJsdoc({
     '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;
@@ -243,12 +258,11 @@ export default async function openapiJsonrpcJsdoc({
 
     const schema = {
       post: {
-        operationId: filename,
+        operationId: apiName,
         deprecated: module.deprecated || false,
-        summary: `/${apiName}`,
+        summary: module.summary ?? `/${apiName}`,
         description: module.description,
         tags: Array.from(tags),
-        parameters: [],
         responses: {
           '200': {
             description: 'OK',
@@ -300,9 +314,12 @@ export default async function openapiJsonrpcJsdoc({
       },
     };
     if (module.params) {
-      let exampleJSON = null;
+      const prevObject = {};
       if (module.examples?.length) {
-        exampleJSON = JSON.parse(module.examples[0]);
+        const exampleJSON = JSON.parse(module.examples[0]);
+        if (exampleJSON) {
+          prevObject['default'] = exampleJSON;
+        }
       }
 
       const propertiesParameters = module.params.reduce(
@@ -313,15 +330,16 @@ export default async function openapiJsonrpcJsdoc({
           if (!parameter.type) {
             throw new Error('JSDoc parameter error: ' + apiName);
           }
-          // todo поддержать не только object поле в аргументе функции
-          if (parameter.type.names[0] === 'object') {
+          // если главный параметр объявлен как объект - пропускаем его
+          if (parameter.type.names.every(name => name.toLowerCase() === 'object')) {
             return accumulator;
           }
+          const isPlain = !parameter.name.includes('.');
 
           const name = extractName(parameter.name);
-          accumulator.properties[name] = accumulator.properties[name] ?? {};
+          const prop = {};
           const description = parameter.description;
-          const defaultValue = parameter.defaultvalue;
+          let defaultValue = parameter.defaultvalue;
 
           const {
             items,
@@ -332,45 +350,63 @@ export default async function openapiJsonrpcJsdoc({
             nullable,
           } = resolveSchemaFromTypeNames(parameter.type.names)
           if (!parameter.optional) {
+            if (!accumulator.required) {
+              accumulator.required = [];
+            }
             accumulator.required.push(name);
           }
           if (nullable) {
-            accumulator.properties[name].nullable = nullable;
+            prop.nullable = nullable;
           }
-          if (defaultValue) {
-            accumulator.properties[name].default = defaultValue;
+          if (defaultValue !== undefined) {
+            // fix for array type if it is not properly closed in JSDoc
+            if (typeof defaultValue === 'string' && defaultValue.startsWith('[') && !defaultValue.endsWith(']')) {
+              defaultValue += ']';
+            }
+            prop.default = JSON.parse(defaultValue);
           }
           if (constant) {
-            accumulator.properties[name].const = constant;
+            prop.const = constant;
           }
           if (format) {
-            accumulator.properties[name].format = format;
+            prop.format = format;
           }
           if (enumData) {
-            accumulator.properties[name].enum = enumData;
+            prop.enum = enumData;
           }
           if (type) {
-            accumulator.properties[name].type = type;
+            prop.type = type;
           }
           if (description) {
-            accumulator.properties[name].description = description;
+            prop.description = description;
           }
           if (items) {
-            accumulator.properties[name].items = items;
+            prop.items = items;
           }
+          if (isPlain) {
+            accumulator = Object.assign(accumulator, prop);
+          } else if (accumulator.properties) {
+            accumulator.properties[name] = prop;
+          } else {
+            accumulator.properties = {
+              [name]: prop,
+            };
+          }
+
           return accumulator;
         },
-        {
-          title: 'Parameters',
-          type: 'object',
-          'default': exampleJSON,
-          required: [],
-          properties: {},
-        },
+        prevObject,
       );
-      if (exampleJSON !== null) {
+      if (Object.keys(propertiesParameters).length) {
         const schemaPostJsdoc = schema.post.requestBody.content['application/json'].schema;
-        schemaPostJsdoc.properties.params = propertiesParameters;
+        if (propertiesParameters.properties) {
+          schemaPostJsdoc.properties.params = {
+            type: 'object',
+            ...propertiesParameters,
+          };
+        } else {
+          schemaPostJsdoc.properties.params = propertiesParameters;
+        }
       }
     }
     temporaryDocument.paths[`${api}${apiName}`] = schema;

package/package.json

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