Skip to content

Commit 7ace3c9

Browse files
marle3003marle3003
committed
doc: update documentation and styles
1 parent ae59662 commit 7ace3c9

2 files changed

Lines changed: 120 additions & 47 deletions

File tree

‎docs/get-started/test-data.md‎

Lines changed: 117 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,52 @@
11
---
2-
title: Mocking APIs with Realistic Test Data
2+
title: Generate Realistic Test Data
33
description: Mokapi generates random realistic test data or lets you customize responses with JavaScript to match your specific use case and scenarios.
4+
subtitle: Mokapi automatically generates realistic test data from your API specifications. Customize responses with JavaScript or use declarative formats to match your exact testing needs.
5+
cards:
6+
items:
7+
- title: Dashboard Guide
8+
href: docs/get-started/dashboard
9+
description: Learn how to validate and visualize your mock data
10+
- title: Write Scripts
11+
href: /docs/javascript-api/overview
12+
description: Add dynamic behavior to your mocks with JavaScript
13+
- title: Configure Mokapi
14+
href: /docs/configuration/overview
15+
description: Customize ports, providers, and other settings
16+
- title: Explore Tutorials
17+
href: /resources
18+
description: Follow step-by-step guides for REST, Kafka, LDAP, and SMTP
419
---
520

6-
# Mocking APIs with Realistic Test Data
21+
# Generate Realistic Test Data
722

823
Creating reliable test data is essential for accurate API testing and development.
924
Mokapi provides a powerful data generation engine that creates realistic test data
10-
based on API specifications. You can customize and control the generated data using
11-
JavaScript scripts or declarative configurations to adapt it to real-world scenarios.
25+
based on your API specifications.
26+
27+
You have multiple options for controlling generated data:
28+
29+
- **Automatic Generation**
30+
Mokapi analyzes your schema and generates context-aware, realistic data automatically
31+
- **Declarative Formats**
32+
Use standard formats like `date`, `email`, `uuid` in your schema
33+
- **JavaScript Customization**
34+
Extend the generator with custom logic for specific fields or patterns
35+
- **Full Response Control**
36+
Write complete response handlers with conditional logic and dynamic behavior
1237

1338
## Automatic Test Data Generation
1439

15-
By default, Mokapi analyzes your API’s data structure and types to generate meaningful responses.
16-
Additionally, Mokapi tailors responses based on request parameters, ensuring relevant data is returned.
17-
For example, if a request filters for available pets, the response will include only pets with the status *available*.
40+
By default, Mokapi analyzes your API's data structure and types to generate
41+
meaningful responses. It also tailors responses based on request parameters,
42+
ensuring relevant data is returned.
43+
44+
### Context-Aware Generation
45+
46+
For example, if a request filters for available pets, the response includes
47+
only pets with `status: "available":
1848

19-
```bash tab=/pet/4
49+
```bash tab=Single Pet
2050
GET http://localhost/api/v3/pet/4
2151
HTTP/1.1 200 OK
2252
Content-Type: application/json
@@ -39,7 +69,7 @@ Content-Type: application/json
3969
"status": "pending"
4070
}
4171
```
42-
```bash tab=/pet/findByStatus
72+
```bash tab=Filtered List
4373
GET http://localhost/api/v3/pet/findByStatus?status=available
4474
HTTP/1.1 200 OK
4575
Content-Type: application/json
@@ -54,17 +84,57 @@ Content-Type: application/json
5484
]
5585
```
5686

57-
## Extending Data Generator with JavaScript
87+
Notice how the status field in the second example matches the query parameter.
88+
Mokapi understands the request context and generates appropriate data.
89+
90+
## Declarative Formats in Schema
91+
92+
Use standard OpenAPI formats to generate specific data types automatically.
93+
Mokapi recognizes these formats and produces realistic values:
94+
95+
| Format | Type | Example Output |
96+
|---------------|----------|-----------------------------------------------------------|
97+
| date | string | 2017-07-21 |
98+
| time | string | 17:32:28Z |
99+
| date-time | string | 2017-07-21T17:32:28Z |
100+
| email | string | shanellewehner@cruickshank.biz |
101+
| uuid | string | dd5742d1-82ad-4d42-8960-cb21bd02f3e7 |
102+
| uri | string | http://www.regionale-enable.info/virtual/portals/redefine |
103+
| password | string | w*YoR94jFL@X |
104+
| ipv4 | string | 68.244.174.93 |
105+
| {zip} {city} | string | 82910 San Jose |
58106

59-
Mokapi’s test data engine is highly extensible using JavaScript, allowing you to customize responses
60-
based on specific attributes. In the example below, a random value from a predefined list is assigned to the frequency attribute.
107+
### Example Schema
61108

62-
``` box=info
63-
It’s recommended to define possible values using an enum in your API specification. This allows Mokapi to randomly
64-
select a value from the list and clearly document all available options for your API users. This example demonstrates
65-
the flexibility Mokapi offers.
109+
```yaml
110+
schema:
111+
type: object
112+
properties:
113+
date:
114+
type: string
115+
format: date # 2017-07-21
116+
time:
117+
type: string
118+
format: date-time # 2017-07-21T17:32:28Z
119+
email:
120+
type: string
121+
format: email # demetrisdach@yost.org
122+
guid:
123+
type: string
124+
format: uuid # dd5742d1-82ad-4d42-8960-cb21bd02f3e7
66125
```
67126
127+
This declarative approach requires no JavaScript, just add the `format` field to your schema.
128+
129+
## Customize with JavaScript
130+
131+
For more control, extend Mokapi's data generator with JavaScript. This is useful
132+
when you need values from a specific list, complex patterns, or custom logic.
133+
134+
### Example: Custom Enum Values
135+
136+
Generate random values from a predefined list:
137+
68138
```javascript
69139
import { fake, findByName, ROOT_NAME } from 'mokapi/faker';
70140
@@ -81,12 +151,25 @@ export default function() {
81151
};
82152
```
83153

84-
## Scripting API Behavior
154+
Now any field named `frequency` will randomly return one of these values.
155+
156+
``` box=tip title="Best Practice: Use Enums in Spec"
157+
It's recommended to define possible values using `enum` in your OpenAPI
158+
specification. This allows Mokapi to randomly select from the list automatically
159+
and clearly documents all available options for API users. The JavaScript
160+
approach shown here demonstrates Mokapi's flexibility for cases where
161+
enum isn't suitable.
162+
```
163+
164+
## Full Response Control with Scripts
165+
166+
For complete control over API behavior, use Mokapi Scripts to customize
167+
responses, simulate errors, add delays, or implement complex logic.
168+
169+
### Example: Dynamic Time API
85170

86-
Mokapi Script allows you to customize API responses and simulate various behaviors, such as returning specific HTTP
87-
statuses or producing Kafka messages.
171+
Create an API that returns the current timestamp:
88172

89-
Example: A simple time API returning the current timestamp:
90173
```javascript tab=time.js
91174
import {on} from 'mokapi'
92175

@@ -123,34 +206,22 @@ paths:
123206
format: date-time
124207
```
125208
126-
## Declarative Test Data Definition
209+
This script intercepts requests to the `time` operation and returns the current
210+
timestamp instead of a static mock value.
127211

128-
If you prefer a declarative approach, Mokapi uses formats like dates, emails, or UUIDs directly in your schema:
212+
## Validate in the Dashboard
129213

130-
```yaml
131-
schema:
132-
type: object
133-
properties:
134-
date:
135-
type: string
136-
format: date # 2017-07-21
137-
time:
138-
type: string
139-
format: date-time # 2017-07-21T17:32:28Z
140-
email:
141-
type: string
142-
format: email # demetrisdach@yost.org
143-
guid:
144-
type: string
145-
format: uuid # dd5742d1-82ad-4d42-8960-cb21bd02f3e7
146-
```
214+
The Mokapi dashboard lets you:
215+
216+
- **Generate sample data:** See what Mokapi produces for your schemas
217+
- **Validate against spec:** Ensure mock data matches your OpenAPI definition
218+
- **Inspect requests:** View generated responses for different request parameters
219+
- **Test edge cases:** Verify your custom generators work as expected
220+
221+
Access the dashboard at `http://localhost:8080` when Mokapi is running.
147222

148-
## Test and Validate in the Dashboard
149-
In the dashboard, you can easily generate sample data and validate it against your API’s specification.
150-
This allows you to ensure your mock data matches the expected structure and behavior. The following chapter will
151-
guide you through the process in more detail.
223+
## What's Next?
152224

153-
## Next Steps
225+
Explore related topics to get more out of Mokapi's test data generation:
154226

155-
- [Using Mokapi's Dashboard](dashboard.md)
156-
- [Explore Mokapi Scripts](../javascript-api/overview.md)
227+
{{ card-grid key="cards" }}

‎webui/src/views/DocsView.vue‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -568,7 +568,9 @@ a[name] {
568568
.content p.subtitle {
569569
margin-bottom: 1.6rem;
570570
font-size: 1.2rem;
571-
font-weight: 400;
571+
font-weight: 550;
572+
line-height: 1.6;
573+
color: rgba(var(--bs-secondary-rgb))
572574
}
573575
574576
.tags {

0 commit comments

Comments
 (0)