openapi-jsonrpc-jsdoc 1.1.2 → 1.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Deni Baskovsky
+Copyright (c) 2019 Denis Baskovsky
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -13,6 +13,7 @@ npm i openapi-jsonrpc-jsdoc --save-dev
 ```js
 // api/api-v1.js
 /**
+ * @json-rpc
  * @description Название API
  * @param {object} parameters - params
  * @param {string} parameters.id - id

package/index.js

@@ -13,6 +13,7 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
     dictionaries: ['jsdoc'],
     hierarchy: true,
   });
+  const tags = new Set();
   const temporaryDocument = {
     'x-send-defaults': true,
     'openapi': '3.0.0',
@@ -21,7 +22,7 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
     'x-explorer-enabled': true,
     'x-proxy-enabled': true,
     'x-samples-enabled': true,
-    'x-samples-languages': ['curl', 'node', 'javascript'],
+    'x-samples-languages': ['node', 'javascript'],
     'info': {
       version: package_.version,
       title: package_.name,
@@ -60,15 +61,31 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
     ],
     'tags': [],
   };
-  for (const module of documents) {
+  const requiredSchema = ['method', 'id', 'jsonrpc'];
+  prepare: for (const module of documents) {
+    let isJsonRpc = false;
+
+    if (module.tags && Array.isArray(module.tags)) {
+      for (const {title, value} of module.tags) {
+        if (title === 'json-rpc') {
+          isJsonRpc = true;
+        } else if (title === 'tags' && value) {
+          value.split(',').map(t => t.trim()).forEach(t => tags.add(t));
+        }
+      }
+    }
+    if (!isJsonRpc) {
+      continue prepare;
+    }
     const apiName = module.meta.filename.replace(/.js$/, '');
+
     const schema = {
       post: {
         operationId: `${module.meta.filename}`,
         deprecated: module.deprecated || false,
         summary: `/${apiName}`,
         description: module.description,
-        tags: ['JSONRPC'],
+        tags: Array.from(tags),
         parameters: [],
         responses: {
           '200': {
@@ -97,7 +114,7 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
             'application/json': {
               schema: {
                 type: 'object',
-                required: ['method', 'id', 'jsonrpc'],
+                required: requiredSchema,
                 properties: {
                   method: {
                     type: 'string',
@@ -114,7 +131,7 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
                   jsonrpc: {
                     type: 'string',
                     default: '2.0',
-                    description: 'JSON-RPC Version (2.0)',
+                    description: 'JSON-RPC 2.0 protocol',
                   },
                 },
               },
@@ -124,10 +141,15 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
       },
     };
     if (module.params) {
+      let exampleJSON = null;
+      if (module.examples?.length) {
+        exampleJSON = JSON.parse(module.examples[0]);
+      }
+
       const propertiesParameters = module.params.reduce(
         (accumulator, parameter) => {
           if (!parameter.type) {
-            throw new Error('JSDOC parameter error: ' + apiName);
+            throw new Error('JSDoc parameter error: ' + apiName);
           }
           // todo поддержать не только object поле в аргументе функции
           if (parameter.type.names[0] === 'object') {
@@ -141,7 +163,9 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
           } catch {
             name = parameter.name;
           }
-          accumulator.required.push(name);
+          if (!parameter.optional) {
+            accumulator.required.push(name);
+          }
           accumulator.properties = {
             ...accumulator.properties,
             [name]: {
@@ -154,17 +178,14 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
         {
           title: 'Parameters',
           type: 'object',
-          'default': module.examples?.length ? JSON.parse(module.examples[0]) : null,
-          required: ['method', 'id', 'jsonrpc'],
+          'default': exampleJSON,
+          required: requiredSchema,
           properties: {},
         },
       );
-      schema.post.requestBody.content['application/json'].schema.required.push(
-        'params',
-      );
-      schema.post.requestBody.content[
-        'application/json'
-        ].schema.properties.params = propertiesParameters;
+      const schemaPostJsdoc = schema.post.requestBody.content['application/json'].schema;
+      schemaPostJsdoc.required.push('params');
+      schemaPostJsdoc.properties.params = propertiesParameters;
     }
     temporaryDocument.paths[`${api}${apiName}`] = schema;
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openapi-jsonrpc-jsdoc",
-  "version": "1.1.2",
-  "description": "OpenAPI generator",
+  "version": "1.2.1",
+  "description": "Transform JSDoc-annotated JSON-RPC 2.0 methods into OpenAPI 3.0 specifications. Auto-generates REST API documentation with complete schemas, parameters, and endpoint definitions.",
   "main": "index.js",
   "scripts": {
     "test": "NODE_NO_WARNINGS=1 ava test/*.test.js"
@@ -33,9 +33,9 @@
   "devDependencies": {
     "ava": "~3.15.0",
     "express": "~5.1.0",
-    "express-openapi-validator": "~5.5.3"
+    "express-openapi-validator": "~5.6.0"
   },
   "engines": {
-    "node": ">= 16"
+    "node": ">= 18"
   }
 }