@noego/stitch 1.0.0

package/docs/modules.md

@@ -0,0 +1,175 @@
+# Module Support in OpenAPI Configuration
+
+This document explains how to use the module feature in your OpenAPI configuration to organize API routes into logical groups.
+
+## Overview
+
+The module feature allows you to define groups of related API endpoints with a common base path. This helps in:
+
+1. Better organization of your API specification
+2. Avoiding duplication of base paths
+3. Keeping related endpoints grouped together
+
+## Configuration
+
+### Adding Modules to Your OpenAPI Document
+
+To use modules, add a top-level `module` field to your OpenAPI document:
+
+```yaml
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.0.0
+paths:
+  # Top-level paths go here
+  
+# Module definitions
+module:
+  user:  # Module name
+    basePath: "/users"  # Common prefix for all routes in this module
+    paths:
+      # Module-specific paths
+      "/": 
+        get:
+          x-controller: user.controller
+          x-action: getAll
+          # Other operation properties...
+      
+      "/{id}":
+        get:
+          x-controller: user.controller
+          x-action: get
+          # Other operation properties...
+```
+
+### Module Properties
+
+Each module requires:
+
+1. `basePath`: The common URL prefix for all routes in this module
+2. `paths`: An object or array containing the module's endpoint definitions
+
+The `basePath` will be combined with each path in the `paths` object to create the full route path.
+
+### Defining Paths
+
+You can define paths in two ways:
+
+#### Object Format (Recommended)
+
+Use an object where keys are path suffixes and values are the path configurations:
+
+```yaml
+module:
+  post:
+    basePath: "/posts"
+    paths:
+      "/": 
+        get:
+          x-controller: post.controller
+          x-action: getAll
+          # ...
+      
+      "/{id}":
+        get:
+          x-controller: post.controller
+          x-action: get
+          # ...
+```
+
+#### Array Format (Alternative)
+
+Define paths as an array of strings with a separate `pathObjects` property:
+
+```yaml
+module:
+  post:
+    basePath: "/posts"
+    paths: ["/", "/{id}", "/create"]
+    pathObjects:
+      "/":
+        get:
+          x-controller: post.controller
+          x-action: getAll
+          # ...
+      
+      "/{id}":
+        get:
+          x-controller: post.controller
+          x-action: get
+          # ...
+```
+
+## How It Works
+
+When the server starts:
+
+1. The OpenAPI parser reads the document and processes all modules
+2. Each module path is combined with its base path to create complete paths
+3. These combined paths are added to the main `paths` object
+4. Routes are created as normal from the final paths object
+
+## Example
+
+Here's a complete example:
+
+```yaml
+openapi: 3.0.0
+info:
+  title: Blog API
+  version: 1.0.0
+paths:
+  # Global routes outside of modules
+  /health:
+    get:
+      x-controller: health.controller
+      x-action: check
+      summary: Health check endpoint
+
+# Module definitions
+module:
+  user:
+    basePath: "/users"
+    paths:
+      "/":
+        get:
+          x-controller: user.controller
+          x-action: getAll
+          summary: Get all users
+      
+      "/{id}":
+        get:
+          x-controller: user.controller
+          x-action: get
+          summary: Get user by ID
+  
+  post:
+    basePath: "/posts"
+    paths:
+      "/":
+        get:
+          x-controller: post.controller
+          x-action: getAll
+          summary: Get all posts
+      
+      "/{id}":
+        get:
+          x-controller: post.controller
+          x-action: get
+          summary: Get post by ID
+```
+
+This will create the following routes:
+- `GET /health`
+- `GET /users/`
+- `GET /users/{id}`
+- `GET /posts/`
+- `GET /posts/{id}`
+
+## Best Practices
+
+1. Use modules to group related functionality
+2. Ensure basePath is meaningful and follows REST conventions
+3. Keep paths consistent within modules
+4. Document your module structure for other developers