Enhance OpenAPI documentation and examples; update server URL and test script

Author: Денис

.gitignore

@@ -1,2 +1,3 @@
 node_modules/
-.idea/
+.idea/
+out/

README.md

@@ -1,26 +1,34 @@
 # openapi-jsonrpc-jsdoc
 
 ## Install
+
 ```fish
 npm i openapi-jsonrpc-jsdoc --save-dev
 ```
 
-## Example
+## Examples
 
 ### Create JSON-RPC Method
+
 ```js
 // api/api-v1.js
 /**
-  * @description Название API
-  * @param {object} parameters - params
-  * @param {string} parameters.id - id
-  */
+ * @description Название API
+ * @param {object} parameters - params
+ * @param {string} parameters.id - id
+ * @example
+ * {
+ *    "@context": "https://www.w3.org/ns/activitystreams",
+ *    "type": "Note"
+ * }
+ */
 module.exports = (parameters) => {
     return parameters.id;
 }
 ```
 
 ### Run package
+
 ```js
 // index.js
 const fs = require('fs');
@@ -40,7 +48,7 @@ openapiJSONRpcJSDoc({
 ```
 
 <details>
-<summary>See result</summary>
+<summary>See Swagger result</summary>
 
 ```json
 {
@@ -57,29 +65,46 @@ openapiJSONRpcJSDoc({
     "javascript"
   ],
   "info": {
-    "version": "1.0.0",
-    "title": "project-name",
-    "description": "project-description"
+    "version": "1.0.4",
+    "title": "openapi-jsonrpc-jsdoc",
+    "description": "OpenAPI generator"
   },
   "servers": [
     {
-      "url": "0.0.0.0:8080"
+      "url": "http://0.0.0.0:9000"
     }
   ],
   "paths": {
-    "/api/api-v1": {
+    "/api/v1": {
       "post": {
-        "operationId": "api-v1.js",
+        "operationId": "v1.js",
         "deprecated": false,
-        "summary": "/api-v1",
+        "summary": "/v1",
         "description": "Название API",
         "tags": [
           "JSONRPC"
         ],
         "parameters": [],
         "responses": {
           "200": {
-            "description": "OK"
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "unexpected error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
           }
         },
         "requestBody": {
@@ -96,8 +121,8 @@ openapiJSONRpcJSDoc({
                 "properties": {
                   "method": {
                     "type": "string",
-                    "default": "api-v1",
-                    "description": "API method api-v1"
+                    "default": "v1",
+                    "description": "API method v1"
                   },
                   "id": {
                     "type": "integer",
@@ -113,7 +138,14 @@ openapiJSONRpcJSDoc({
                   "params": {
                     "title": "Parameters",
                     "type": "object",
+                    "default": {
+                      "@context": "https://www.w3.org/ns/activitystreams",
+                      "type": "Note"
+                    },
                     "required": [
+                      "method",
+                      "id",
+                      "jsonrpc",
                       "id"
                     ],
                     "properties": {
@@ -129,6 +161,72 @@ openapiJSONRpcJSDoc({
           }
         }
       }
+    },
+    "/api/v2": {
+      "post": {
+        "operationId": "v2.js",
+        "deprecated": true,
+        "summary": "/v2",
+        "description": "Название API 2",
+        "tags": [
+          "JSONRPC"
+        ],
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "unexpected error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "method",
+                  "id",
+                  "jsonrpc"
+                ],
+                "properties": {
+                  "method": {
+                    "type": "string",
+                    "default": "v2",
+                    "description": "API method v2"
+                  },
+                  "id": {
+                    "type": "integer",
+                    "default": 1,
+                    "format": "int32",
+                    "description": "Request ID"
+                  },
+                  "jsonrpc": {
+                    "type": "string",
+                    "default": "2.0",
+                    "description": "JSON-RPC Version (2.0)"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
     }
   },
   "components": {
@@ -137,6 +235,27 @@ openapiJSONRpcJSDoc({
         "type": "http",
         "scheme": "digest"
       }
+    },
+    "schemas": {
+      "Error": {
+        "required": [
+          "error",
+          "id",
+          "jsonrpc"
+        ],
+        "properties": {
+          "id": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "error": {
+            "type": "object"
+          },
+          "jsonrpc": {
+            "type": "string"
+          }
+        }
+      }
     }
   },
   "security": [

index.js

@@ -5,9 +5,12 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
     files,
     package: packageUrl,
     access: 'public',
+    encoding: 'utf8',
     module: true,
     undocumented: false,
     sort: 'scope',
+    allowUnknownTags: true,
+    dictionaries: ['jsdoc'],
     hierarchy: true,
   });
   const temporaryDocument = {
@@ -143,7 +146,6 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
             ...accumulator.properties,
             [name]: {
               type,
-              // default: ...,// fixme: настроить выдачу default значения по JSON-DOC
               description,
             },
           };
@@ -152,6 +154,7 @@ 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'],
           properties: {},
         },
@@ -168,4 +171,4 @@ async function openapiJsonrpcJsdoc({ files, securitySchemes = {}, packageUrl, se
   return temporaryDocument;
 }
 
-module.exports = openapiJsonrpcJsdoc;
+module.exports = openapiJsonrpcJsdoc;

package.json

@@ -4,7 +4,7 @@
   "description": "OpenAPI generator",
   "main": "index.js",
   "scripts": {
-    "test": "ava test/*.test.js"
+    "test": "NODE_NO_WARNINGS=1 ava test/*.test.js"
   },
   "repository": {
     "type": "git",

test/api/v1.js

@@ -2,7 +2,12 @@
  * @description Название API
  * @param {object} parameters - params
  * @param {string} parameters.id - id
+ * @example
+ * {
+ *    "@context": "https://www.w3.org/ns/activitystreams",
+ *    "type": "Note"
+ * }
  */
 module.exports = (parameters) => {
   return parameters.id;
-};
+};

test/index.test.js

@@ -46,10 +46,10 @@ test.before(async t => {
     },
     servers: [
       {
-        url: '0.0.0.0:' + port,
+        url: 'http://0.0.0.0:' + port,
       },
     ],
-    packageUrl: './package.json',
+    packageUrl: path.resolve('./package.json'),
     files: './test/api/*.js',
   });
 });