openapi-jsonrpc-jsdoc 1.5.2 → 1.5.4

package/index.mjs

@@ -29,6 +29,15 @@ function isBigInt64(n) {
   }
 }
 
+function normalizeString(s) {
+  if (
+      (s.startsWith("'") && s.endsWith("'"))
+      || (s.startsWith('"') && s.endsWith('"'))
+  ) {
+    return s.slice(1, -1);
+  }
+}
+
 function resolveSchemaFromTypeNames(names) {
   let type;
   let format;
@@ -92,8 +101,10 @@ function resolveSchemaFromTypeNames(names) {
           return Number(n);
         } else if (isBigInt64(n)) {
           return n;
+        } else if (typeof n === 'string') {
+          return normalizeString(n)
         }
-        return String(n);
+        return s;
       });
 
       if (enumData.every(n => Number.isSafeInteger(n))) {
@@ -224,6 +235,16 @@ export default async function openapiJsonrpcJsdoc({
             },
             error: {
               type: 'object',
+              required: ['code', 'message'],
+              properties: {
+                code: {
+                  type: 'integer',
+                  default: -32001,
+                },
+                message: {
+                  type: 'string',
+                },
+              },
             },
             jsonrpc: {
               type: 'string',
@@ -242,10 +263,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));
         }
       }
@@ -256,26 +277,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: apiName,
         deprecated: module.deprecated || false,
         summary: module.summary ?? `/${apiName}`,
-        description: module.description,
+        description: description,
         tags: Array.from(tags),
         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: {
@@ -295,16 +339,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',
                   },
                 },
               },
@@ -314,89 +360,85 @@ export default async function openapiJsonrpcJsdoc({
       },
     };
     if (module.params) {
-      const prevObject = {};
+      let propertiesParameters = {};
+      let required = [];
+
       if (module.examples?.length) {
         const exampleJSON = JSON.parse(module.examples[0]);
         if (exampleJSON) {
-          prevObject['default'] = exampleJSON;
+          propertiesParameters['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);
-          }
-          // если главный параметр объявлен как объект - пропускаем его
-          if (parameter.type.names.every(name => name.toLowerCase() === 'object')) {
-            return accumulator;
-          }
-          const isPlain = !parameter.name.includes('.');
+      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);
-          const prop = {};
-          const description = parameter.description;
-          let 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) {
-            if (!accumulator.required) {
-              accumulator.required = [];
-            }
-            accumulator.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 += ']';
-            }
-            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) {
-            accumulator = Object.assign(accumulator, prop);
-          } else if (accumulator.properties) {
-            accumulator.properties[name] = prop;
-          } else {
-            accumulator.properties = {
-              [name]: prop,
-            };
+        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 += ']';
           }
+          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;
 
-          return accumulator;
-        },
-        prevObject,
-      );
       if (Object.keys(propertiesParameters).length) {
         const schemaPostJsdoc = schema.post.requestBody.content['application/json'].schema;
         if (propertiesParameters.properties) {

package/package.json

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