openapi-jsonrpc-jsdoc 1.5.1 → 1.5.3

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'};
@@ -216,6 +224,16 @@ export default async function openapiJsonrpcJsdoc({
             },
             error: {
               type: 'object',
+              required: ['code', 'message'],
+              properties: {
+                code: {
+                  type: 'integer',
+                  default: -32001,
+                },
+                message: {
+                  type: 'string',
+                },
+              },
             },
             jsonrpc: {
               type: 'string',
@@ -234,10 +252,10 @@ export default async function openapiJsonrpcJsdoc({
     const tags = new Set();
 
     if (module.tags && Array.isArray(module.tags)) {
-      for (const {title, value} of module.tags) {
+      for (const {title, originalTitle, value} of module.tags) {
         if (title === 'json-rpc') {
           isJsonRpc = true;
-        } else if (value && ['tags', 'tag'].includes(title)) {
+        } else if (value && ['tags', 'tag'].includes(originalTitle ?? title)) {
           value.split(',').map(t => t.trim()).forEach(t => tags.add(t));
         }
       }
@@ -248,27 +266,49 @@ export default async function openapiJsonrpcJsdoc({
     const {filename} = module.meta;
     const apiName = filename.replace(/\.js$/, '');
 
+    let resultValues;
+    switch (module.returns?.[0]?.description) {
+      case 'Promise<*>':
+      case 'Promise<object>': {
+        resultValues = 'object';
+        break;
+      }
+      default: {
+        resultValues = '';
+        break;
+      }
+    }
+
+    let description = module.description;
+    if (module.todo?.length) {
+      description += '\n\nTODO: ' + module.todo.join();
+    }
+
     const schema = {
       post: {
-        operationId: filename,
+        operationId: apiName,
         deprecated: module.deprecated || false,
-        summary: `/${apiName}`,
-        description: module.description,
+        summary: module.summary ?? `/${apiName}`,
+        description: description,
         tags: Array.from(tags),
-        parameters: [],
         responses: {
           '200': {
-            description: 'OK',
+            description: 'OK response',
             content: {
               'application/json': {
                 schema: {
                   type: 'object',
+                  properties: {
+                    result: {
+                      type: resultValues,
+                    },
+                  },
                 },
               },
             },
           },
-          default: {
-            description: 'unexpected error',
+          '400': {
+            description: 'Unexpected error',
             content: {
               'application/json': {
                 schema: {
@@ -288,16 +328,18 @@ export default async function openapiJsonrpcJsdoc({
                 properties: {
                   method: {
                     type: 'string',
-                    description: `API method ${apiName}`,
+                    'default': apiName,
+                    description: `API method header`,
                   },
                   id: {
                     type: ['string', 'integer'],
-                    description: 'Request ID',
+                    default: 'swagger_unique_indentifier',
+                    description: 'Request ID header',
                   },
                   jsonrpc: {
                     type: 'string',
                     default: '2.0',
-                    description: 'JSON-RPC 2.0 protocol',
+                    description: 'JSON-RPC 2.0 header',
                   },
                 },
               },
@@ -307,77 +349,95 @@ 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(
-        (accumulator, parameter) => {
-          if (parameter.name.startsWith('_')) {
-            return accumulator;
-          }
-          if (!parameter.type) {
-            throw new Error('JSDoc parameter error: ' + apiName);
-          }
-          // todo поддержать не только object поле в аргументе функции
-          if (parameter.type.names[0] === 'object') {
-            return accumulator;
-          }
+      let propertiesParameters = {};
+      let required = [];
+      for (const parameter of module.params) {
+        if (parameter.name.startsWith('_')) {
+          continue;
+        }
+        if (!parameter.type) {
+          throw new Error('JSDoc parameter error: ' + apiName);
+        }
+        // если главный параметр объявлен как объект - пропускаем его
+        if (parameter.type.names.every(name => name.toLowerCase() === 'object')) {
+          continue;
+        }
+        const isPlain = !parameter.name.includes('.');
 
-          const name = extractName(parameter.name);
-          accumulator.properties[name] = accumulator.properties[name] ?? {};
-          const description = parameter.description;
-          const defaultValue = parameter.defaultvalue;
+        const name = extractName(parameter.name);
+        const prop = {};
+        const description = parameter.description;
+        let defaultValue = parameter.defaultvalue;
 
-          const {
-            items,
-            constant,
-            enumData,
-            type,
-            format,
-            nullable,
-          } = resolveSchemaFromTypeNames(parameter.type.names)
-          if (!parameter.optional) {
-            accumulator.required.push(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;
-          }
-          if (description) {
-            accumulator.properties[name].description = description;
-          }
-          if (items) {
-            accumulator.properties[name].items = items;
+        const {
+          items,
+          constant,
+          enumData,
+          type,
+          format,
+          nullable,
+        } = resolveSchemaFromTypeNames(parameter.type.names)
+        if (!parameter.optional) {
+          required.push(name);
+        }
+        if (nullable) {
+          prop.nullable = nullable;
+        }
+        if (defaultValue !== undefined) {
+          // fix for array type if it is not properly closed in JSDoc
+          if (typeof defaultValue === 'string' && defaultValue.startsWith('[') && !defaultValue.endsWith(']')) {
+            defaultValue += ']';
           }
-          return accumulator;
-        },
-        {
-          title: 'Parameters',
-          type: 'object',
-          'default': exampleJSON,
-          required: [],
-          properties: {},
-        },
-      );
-      if (exampleJSON !== null) {
+          prop.default = JSON.parse(defaultValue);
+        }
+        if (constant) {
+          prop.const = constant;
+        }
+        if (format) {
+          prop.format = format;
+        }
+        if (enumData) {
+          prop.enum = enumData;
+        }
+        if (type) {
+          prop.type = type;
+        }
+        if (description) {
+          prop.description = description;
+        }
+        if (items) {
+          prop.items = items;
+        }
+        if (isPlain) {
+          propertiesParameters = Object.assign(propertiesParameters, prop);
+        } else if (propertiesParameters.properties) {
+          propertiesParameters.properties[name] = prop;
+        } else {
+          propertiesParameters.properties = {
+            [name]: prop,
+          };
+        }
+      }
+      propertiesParameters.required = required;
+
+      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.1",
+  "version": "1.5.3",
   "description": "Transform JSDoc-annotated JSON-RPC 2.0 methods into OpenAPI specifications.",
   "main": "index.mjs",
   "type": "module",