DMC/apimposter
0
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Releases Activity

Add index-support, type hints and improve documentation #4

Merged
stne3960 merged 3 commits from feature/allow_index into main 2025-06-16 12:41:04 +02:00
Conversation 0 Commits 3 Files Changed 3 +100 -49
1 changed files with 100 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 82002ce730 - Show all commits

149
README.md
View File

@ -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
# 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.
You can reference global values using `{globals.key}` or `{globals.key:type}` in responses.
---
## 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" }