@avtechno/sfr 2.0.9 → 2.1.1

package/dist/index.mjs

@@ -22,6 +22,8 @@ async function write_service_discovery(cfg, documents) {
     //Setup files in case they do not exist.
     //Setup output folder
     await fs.mkdir(path.join(cwd, cfg.out), { recursive: true });
+    // Write combined OpenAPI index file containing all protocols
+    await write_combined_openapi_index(cfg, documents);
     // Loop over each protocol
     for (let [protocol, documentation] of Object.entries(documents)) {
         //Strictly await for setup to create dirs for each protocol.
@@ -51,6 +53,38 @@ async function write_service_discovery(cfg, documents) {
         }
     }
 }
+// Writes a combined openapi.yml index file containing all generated documentation
+async function write_combined_openapi_index(cfg, documents) {
+    const combined = {
+        openapi: "3.1.0",
+        info: {},
+        paths: {},
+        components: {
+            schemas: {}
+        }
+    };
+    for (const [protocol, documentation] of Object.entries(documents)) {
+        switch (protocol) {
+            case "REST":
+                {
+                    const rest_doc = documentation;
+                    // Merge REST OpenAPI info, paths, and components into combined doc
+                    combined.info = rest_doc.info;
+                    combined.paths = rest_doc.paths;
+                    // Merge component schemas if they exist
+                    if (rest_doc.components?.schemas) {
+                        combined.components.schemas = {
+                            ...combined.components.schemas,
+                            ...rest_doc.components.schemas
+                        };
+                    }
+                }
+                break;
+        }
+    }
+    // Write the combined index file
+    await fs.writeFile(path.join(cwd, cfg.out, "openapi.yml"), yaml.dump(combined, { lineWidth: -1, indent: 2, noRefs: true }), { flag: "w+" });
+}
 //Tasked with recursively creating directories and spec files.
 async function write_to_file(cfg, dir, data) {
     //Path is a slash(/) delimited string, with the end delimiter indicating the filename to be used.

package/dist/sfr-pipeline.mjs

@@ -509,7 +509,10 @@ export class SFRPipeline {
         const spec = {
             openapi: "3.0.0",
             info: Object.assign({}, this.oas_cfg),
-            paths: {}
+            paths: {},
+            components: {
+                schemas: {}
+            }
         };
         // Iterate through each protocol (e.g., REST, WS, MQ)
         Object.entries(declaration).forEach(([namespace, module]) => {
@@ -623,9 +626,30 @@ export class SFRPipeline {
                             document.description = (document.description || "") + rate_limit_note;
                         }
                     }
+                    // Generate schema name from namespace and endpoint
+                    const schema_name = this.generate_schema_name(namespace, endpoint, method);
                     //Insert either a parameter or a requestBody according to the method type
                     if (validator_type === "joi") {
-                        document[method === "GET" ? "parameters" : "requestBody"] = j2s(validator).swagger;
+                        const swagger_schema = j2s(validator).swagger;
+                        if (method === "get") {
+                            // For GET requests, convert schema properties to query parameters
+                            document.parameters = this.convert_schema_to_query_parameters(swagger_schema, schema_name, spec);
+                        }
+                        else {
+                            // For POST/PUT/PATCH/DELETE, use requestBody with application/json
+                            // Store schema in components
+                            spec.components.schemas[schema_name] = swagger_schema;
+                            document.requestBody = {
+                                required: true,
+                                content: {
+                                    "application/json": {
+                                        schema: {
+                                            $ref: `#/components/schemas/${schema_name}`
+                                        }
+                                    }
+                                }
+                            };
+                        }
                     }
                     // Convert Multer validators to multipart/form-data OpenAPI schema
                     if (validator_type === "multer") {
@@ -644,6 +668,71 @@ export class SFRPipeline {
         spec.info.meta = Object.fromEntries(Object.entries(spec.info.meta).map(([k, v]) => [`x-${k}`, v]));
         return spec;
     }
+    /**
+     * Generates a unique schema name from namespace, endpoint, and method.
+     */
+    generate_schema_name(namespace, endpoint, method) {
+        // Convert to PascalCase and create a descriptive schema name
+        const pascal_case = (str) => str
+            .split(/[-_]/)
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+            .join('');
+        const method_prefix = method.charAt(0).toUpperCase() + method.slice(1).toLowerCase();
+        const namespace_part = pascal_case(namespace);
+        const endpoint_part = pascal_case(endpoint);
+        return `${method_prefix}${namespace_part}${endpoint_part}Request`;
+    }
+    /**
+     * Converts a JSON schema to OpenAPI query parameters array.
+     * Stores complex schemas in components and references them.
+     */
+    convert_schema_to_query_parameters(schema, base_name, spec) {
+        const parameters = [];
+        if (!schema || !schema.properties) {
+            return parameters;
+        }
+        const required_fields = schema.required || [];
+        for (const [prop_name, prop_schema] of Object.entries(schema.properties)) {
+            const param_schema = prop_schema;
+            const is_required = required_fields.includes(prop_name);
+            // Check if the property is a complex type (object or array of objects)
+            const is_complex = param_schema.type === 'object' ||
+                (param_schema.type === 'array' && param_schema.items?.type === 'object');
+            if (is_complex) {
+                // Store complex schemas in components and reference them
+                const component_name = `${base_name}${prop_name.charAt(0).toUpperCase() + prop_name.slice(1)}`;
+                spec.components.schemas[component_name] = param_schema;
+                parameters.push({
+                    name: prop_name,
+                    in: "query",
+                    required: is_required,
+                    description: param_schema.description || "",
+                    content: {
+                        "application/json": {
+                            schema: {
+                                $ref: `#/components/schemas/${component_name}`
+                            }
+                        }
+                    }
+                });
+            }
+            else {
+                // Simple types can be defined inline
+                const param = {
+                    name: prop_name,
+                    in: "query",
+                    required: is_required,
+                    schema: { ...param_schema }
+                };
+                if (param_schema.description) {
+                    param.description = param_schema.description;
+                    delete param.schema.description;
+                }
+                parameters.push(param);
+            }
+        }
+        return parameters;
+    }
     // Method to generate an AsyncAPI document from a WSNamespaceDeclaration
     generate_ws_async_api_document(declaration) {
         const spec = {

package/dist/types/sfr-pipeline.d.mts

@@ -68,6 +68,15 @@ export declare class SFRPipeline {
     private bind_mq_fns;
     private spec_generation;
     private generate_open_api_document;
+    /**
+     * Generates a unique schema name from namespace, endpoint, and method.
+     */
+    private generate_schema_name;
+    /**
+     * Converts a JSON schema to OpenAPI query parameters array.
+     * Stores complex schemas in components and references them.
+     */
+    private convert_schema_to_query_parameters;
     private generate_ws_async_api_document;
     private generate_mq_async_api_document;
     private print_to_console;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avtechno/sfr",
-  "version": "2.0.9",
+  "version": "2.1.1",
   "description": "An opinionated way of writing services using ExpressJS.",
   "type": "module",
   "files": [

package/src/index.mts

@@ -31,6 +31,9 @@ async function write_service_discovery(cfg: ParserCFG, documents: ServiceDocumen
   //Setup output folder
   await fs.mkdir(path.join(cwd, cfg.out), { recursive: true });
 
+  // Write combined OpenAPI index file containing all protocols
+  await write_combined_openapi_index(cfg, documents);
+
   // Loop over each protocol
   for (let [protocol, documentation] of Object.entries(documents)) {
     //Strictly await for setup to create dirs for each protocol.
@@ -60,6 +63,44 @@ async function write_service_discovery(cfg: ParserCFG, documents: ServiceDocumen
   }
 }
 
+// Writes a combined openapi.yml index file containing all generated documentation
+async function write_combined_openapi_index(cfg: ParserCFG, documents: ServiceDocuments) {
+  const combined: any = {
+    openapi: "3.1.0",
+    info: {},
+    paths: {},
+    components: {
+      schemas: {}
+    }
+  };
+
+  for (const [protocol, documentation] of Object.entries(documents)) {
+    switch (protocol) {
+      case "REST": {
+        const rest_doc = documentation as OAPI_Document;
+        // Merge REST OpenAPI info, paths, and components into combined doc
+        combined.info = rest_doc.info;
+        combined.paths = rest_doc.paths;
+        
+        // Merge component schemas if they exist
+        if (rest_doc.components?.schemas) {
+          combined.components.schemas = {
+            ...combined.components.schemas,
+            ...rest_doc.components.schemas
+          };
+        }
+      } break;
+    }
+  }
+
+  // Write the combined index file
+  await fs.writeFile(
+    path.join(cwd, cfg.out, "openapi.yml"),
+    yaml.dump(combined, { lineWidth: -1, indent: 2, noRefs: true }),
+    { flag: "w+" }
+  );
+}
+
 //Tasked with recursively creating directories and spec files.
 async function write_to_file(cfg: ParserCFG, dir: string, data: object) {
   //Path is a slash(/) delimited string, with the end delimiter indicating the filename to be used.

package/src/sfr-pipeline.mts

@@ -562,7 +562,10 @@ export class SFRPipeline {
     const spec: OAPI_Document = {
       openapi: "3.0.0",
       info : Object.assign({}, this.oas_cfg),
-      paths: {}
+      paths: {},
+      components: {
+        schemas: {}
+      }
     };
 
     // Iterate through each protocol (e.g., REST, WS, MQ)
@@ -686,9 +689,32 @@ export class SFRPipeline {
             }
           }
 
+          // Generate schema name from namespace and endpoint
+          const schema_name = this.generate_schema_name(namespace, endpoint, method);
+
           //Insert either a parameter or a requestBody according to the method type
-          if(validator_type === "joi"){
-            document[method === "GET" ? "parameters" : "requestBody"] = j2s(validator).swagger;
+          if (validator_type === "joi") {
+            const swagger_schema = j2s(validator).swagger;
+            
+            if (method === "get") {
+              // For GET requests, convert schema properties to query parameters
+              document.parameters = this.convert_schema_to_query_parameters(swagger_schema, schema_name, spec);
+            } else {
+              // For POST/PUT/PATCH/DELETE, use requestBody with application/json
+              // Store schema in components
+              spec.components.schemas[schema_name] = swagger_schema;
+              
+              document.requestBody = {
+                required: true,
+                content: {
+                  "application/json": {
+                    schema: {
+                      $ref: `#/components/schemas/${schema_name}`
+                    }
+                  }
+                }
+              };
+            }
           }
 
           // Convert Multer validators to multipart/form-data OpenAPI schema
@@ -710,6 +736,83 @@ export class SFRPipeline {
     return spec;
   }
 
+  /**
+   * Generates a unique schema name from namespace, endpoint, and method.
+   */
+  private generate_schema_name(namespace: string, endpoint: string, method: string): string {
+    // Convert to PascalCase and create a descriptive schema name
+    const pascal_case = (str: string) => str
+      .split(/[-_]/)
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join('');
+    
+    const method_prefix = method.charAt(0).toUpperCase() + method.slice(1).toLowerCase();
+    const namespace_part = pascal_case(namespace);
+    const endpoint_part = pascal_case(endpoint);
+    
+    return `${method_prefix}${namespace_part}${endpoint_part}Request`;
+  }
+
+  /**
+   * Converts a JSON schema to OpenAPI query parameters array.
+   * Stores complex schemas in components and references them.
+   */
+  private convert_schema_to_query_parameters(schema: any, base_name: string, spec: OAPI_Document): any[] {
+    const parameters: any[] = [];
+    
+    if (!schema || !schema.properties) {
+      return parameters;
+    }
+
+    const required_fields = schema.required || [];
+
+    for (const [prop_name, prop_schema] of Object.entries(schema.properties)) {
+      const param_schema: any = prop_schema;
+      const is_required = required_fields.includes(prop_name);
+      
+      // Check if the property is a complex type (object or array of objects)
+      const is_complex = param_schema.type === 'object' || 
+        (param_schema.type === 'array' && param_schema.items?.type === 'object');
+
+      if (is_complex) {
+        // Store complex schemas in components and reference them
+        const component_name = `${base_name}${prop_name.charAt(0).toUpperCase() + prop_name.slice(1)}`;
+        spec.components.schemas[component_name] = param_schema;
+
+        parameters.push({
+          name: prop_name,
+          in: "query",
+          required: is_required,
+          description: param_schema.description || "",
+          content: {
+            "application/json": {
+              schema: {
+                $ref: `#/components/schemas/${component_name}`
+              }
+            }
+          }
+        });
+      } else {
+        // Simple types can be defined inline
+        const param: any = {
+          name: prop_name,
+          in: "query",
+          required: is_required,
+          schema: { ...param_schema }
+        };
+
+        if (param_schema.description) {
+          param.description = param_schema.description;
+          delete param.schema.description;
+        }
+
+        parameters.push(param);
+      }
+    }
+
+    return parameters;
+  }
+
   // Method to generate an AsyncAPI document from a WSNamespaceDeclaration
   private generate_ws_async_api_document(declaration: WSNamespaceDeclaration): AsyncAPIDocument {
     const spec: any = {