README.md

@@ -10,7 +10,7 @@ APImposter is an easy-to-use service built with Spring Boot, enabling quick mock
 
 ---
 
-## Key Features
+## Features
 
 - **Structured Mock Data:** Organize your mock data in YAML files.
 - **Automatic URL Mapping:** Automatically generates URL structure based on your folder hierarchy and YAML file names.
@@ -18,80 +18,131 @@ APImposter is an easy-to-use service built with Spring Boot, enabling quick mock
 - **Dynamic Responses and Global Placeholders:** Supports dynamic values in responses based on URL parameters and you can define global placeholders to reuse values across multiple responses and systems.
 - **Conditional Responses:** Return different mock responses based on request data (headers, query, body, or path).
 - **Swagger UI:** Automatically generated Swagger UI from YAML files.
-- **Quick Setup:** Easy installation and configuration.
 
 ---
 
 ## Mocks Structure
 
-YAML defined mocks are stored in a directory defined in `application.properties`. You can organize them in nested folders like this:
+Mocks are defined in YAML files and stored in a directory specified via `application.properties`. You can organize them in nested folders:
 
 ```
 /mocks/
 ├── globals.yaml
 ├── system1/
 │   ├── users.yaml
-│   └── program.yaml
+│   └── index.yaml
 └── another-system/
     ├── endpoint1.yaml
     └── subdir/
-        └── endpoint2.yaml
+        ├── endpoint2.yaml
+        └── index.yaml
 ```
 
-Example YAML files:
+### URL Mapping
+
+- `/system1/users.yaml` defines mocks under `/system1/users/...`
+- `/system1/index.yaml` defines mocks under`/system1/...`)
+- Multiple endpoints can be grouped in one file
+- Folders in the YAML file structure become part of the URL path automatically.
+
+### Grouped endpoints in `users.yaml`
 
 ```yaml
-# globals.yaml
+# mocks/system1/users.yaml
+- method: GET
+  path: "/"
+  response:
+    status: 200
+    body:
+      users:
+        - id: 1
+          name: "Alice"
+        - id: 2
+          name: "Bob"
+
+- method: GET
+  path: "/{id}"
+  response:
+    status: 200
+    body:
+      id: "{id:int}"
+      name: "User {id}"
+
+- method: POST
+  path: "/"
+  response:
+    status: 200
+    body:
+      message: "User created"
+```
+
+### Base-level grouping via `index.yaml`
+
+```yaml
+# mocks/system1/index.yaml
+- method: GET
+  path: "/"
+  response:
+    status: 200
+    body:
+      message: "Welcome to system1"
+
+- method: GET
+  path: "/info"
+  response:
+    status: 200
+    body:
+      name: "System One"
+      version: "1.0"
+```
+
+### Placeholder Type Hints
+
+You can include optional type hints in placeholders to ensure JSON values are rendered with correct types.
+
+#### Supported types
+
+| Type    | Placeholder      | Output          |
+|---------|------------------|-----------------|
+| string  | `{name}`         | `"Alice"`       |
+| int     | `{id:int}`       | `42` *(number)* |
+| float   | `{price:float}`  | `99.95`         |
+| boolean | `{enabled:bool}` | `true`          |
+
+If parsing fails (e.g. `abc` for an `int`), APImposter **falls back to the original string**.
+
+---
+
+## Example Requests and Responses
+
+| YAML file                          | Request                          | Response Example                             |
+|------------------------------------|----------------------------------|----------------------------------------------|
+| `system1/users.yaml`               | `GET /system1/users`             | `{ "users": [{ "id": 1 }, { "id": 2 }] }`    |
+| `system1/users.yaml`               | `GET /system1/users/42`          | `{ "id": 42, "name": "User 42" }`            |
+| `system1/users.yaml`               | `POST /system1/users`            | `{ "message": "User created" }`              |
+| `system1/index.yaml`               | `GET /system1`                   | `{ "message": "Welcome to system1" }`        |
+| `system1/index.yaml`               | `GET /system1/info`              | `{ "name": "System One", "version": "1.0" }` |
+| `another-system/subdir/index.yaml` | `GET /another-system/subdir/...` | *(Defined response in file)*                 |
+
+---
+
+## Globals
+
+Global values can be defined in a dedicated file `globals.yaml`:
+
+```yaml
+# mocks/globals.yaml
 globals:
   currentUserId: "user-123"
 ```
 
-```yaml
+You can reference global values using `{globals.key}` or `{globals.key:type}` in responses.
-# system1/users.yaml
-- method: "GET"
-  path: "/{id}"
-  response:
-    status: 200
-    headers:
-      Content-Type: "application/json"
-    body:
-      id: "{id}"
-      name: "Example User"
-```
-
-```yaml
-# system1/program.yaml
-- method: "GET"
-  path: "/"
-  delay: 500
-  response:
-    status: 200
-    headers:
-      Content-Type: "application/json"
-    body:
-      programId: 12345
-      globalUserId: "{globals.currentUserId}"
-```
-
----
-## Example Requests and Responses
-
-| YAML file                               | Request                                    | Response                                  |
-| --------------------------------------- |--------------------------------------------|-------------------------------------------|
-| `mocks/system1/users.yaml`              | `GET /<prefix>/system1/users/123`          | `{ "id": "123", "name": "Example User" }` |
-| `mocks/system1/program.yaml`            | `GET /<prefix>/system1/program`            | `{ "programId": 12345, "globalUserId": "user-123" }` |
-| `mocks/another-system/subdir/endpoint2` | `GET /<prefix>/another-system/subdir/endpoint2/...` | *(defined response JSON)*                 |
-
-Dynamic placeholders in responses (`{id}`) and global placeholders (`{globals.currentUserId}`) are automatically replaced with actual URL parameters or globally defined values.
-
-Folders in the YAML file structure become part of the URL path automatically.
-
 
 ---
 
 ## Conditional Responses
 
-APImposter supports **conditional responses**, allowing different mock responses to be returned **based on request values** — like query parameters, headers, path variables, or body fields.
+APImposter supports **conditional responses**, allowing different mock responses to be returned **based on request values** - query parameters, headers, path variables, or body fields.
 
 This is useful for simulating realistic API behavior, such as authentication, filtering, or alternate success/error outcomes.
 
@@ -184,7 +235,7 @@ This is useful for simulating realistic API behavior, such as authentication, fi
         body:
           products:
             - id: "t1"
-              name: "Mechanical Keyboard"
+              name: "Keyboard"
   response:
     status: 200
     headers: { Content-Type: "application/json" }