Enhance OpenAPI generation by adding dynamic tag handling and updating version to 1.2.0 #4

Author: qertis

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

index.js

@@ -13,6 +13,7 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
     dictionaries: ['jsdoc'],
     hierarchy: true,
   });
+  const tags = [];
   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,
@@ -58,17 +59,25 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
         BasicAuth: [],
       },
     ],
-    'tags': [],
+    'tags': tags,
   };
+  const requiredSchema = ['method', 'id', 'jsonrpc'];
   for (const module of documents) {
     const apiName = module.meta.filename.replace(/.js$/, '');
+
+    if (module.tags && Array.isArray(module.tags)) {
+      for (const tag of module.tags) {
+        tags.push(...new Set(tag.value.split(',').map(t => t.trim())));
+      }
+    }
+
     const schema = {
       post: {
         operationId: `${module.meta.filename}`,
         deprecated: module.deprecated || false,
         summary: `/${apiName}`,
         description: module.description,
-        tags: ['JSONRPC'],
+        tags: tags,
         parameters: [],
         responses: {
           '200': {
@@ -97,7 +106,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 +123,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 +133,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 +155,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 +170,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.json

@@ -1,7 +1,7 @@
 {
   "name": "openapi-jsonrpc-jsdoc",
-  "version": "1.1.2",
-  "description": "OpenAPI generator",
+  "version": "1.2.0",
+  "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"
   }
 }

test/api/v1.js

@@ -2,6 +2,8 @@
  * @description Название API
  * @param {object} parameters - params
  * @param {string} parameters.id - id
+ * @param {string} [parameters.test] - test
+ * @tags api, api-v1, api
  * @example
  * {
  *    "@context": "https://www.w3.org/ns/activitystreams",