dummy_api_overlay

A Flutter developer tool that adds a draggable floating button to your app. Tap it to open a full-screen mock rule manager where you can define URL patterns and dummy JSON responses — no more hardcoding fake data in your codebase.

Works with both http and dio packages. Rules are persisted via shared_preferences and survive hot restarts. The overlay is automatically disabled in release builds.

---

Preview

Overlay button	Rule list	Add / edit rule
Floating draggable FAB	Search, toggle, delete rules	URL, method, status, response body

---

Features

• Draggable overlay button — stays out of the way, shows active rule count badge
• Full-screen rule manager — search, enable/disable individual rules, global master switch
• Flexible URL matching — exact URL, prefix, substring, or full regex
• http & dio support — drop-in client / interceptor, no changes to your existing code
• Persistent rules — saved to shared_preferences, survive hot restart
• JSON export / import — share rule sets with your team
• JSON formatter — one-tap pretty-print in the response body editor
• Debug-only by default — zero impact on release builds

---

Getting started

Add to your pubspec.yaml:

dependencies:
  dummy_api_overlay: ^0.1.0

---

Setup

1. Wrap your MaterialApp

Pass a shared navigatorKey so the overlay can push the rules screen:

import 'package:dummy_api_overlay/dummy_api_overlay.dart';

final _navigatorKey = GlobalKey<NavigatorState>();

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: _navigatorKey,
      builder: (context, child) => DummyApiOverlay(
        navigatorKey: _navigatorKey,
        child: child!,
      ),
      home: HomeScreen(),
    );
  }
}

2a. Use DummyHttpClient (http package)

Replace http.Client() with DummyHttpClient():

import 'package:dummy_api_overlay/dummy_api_overlay.dart';

final client = DummyHttpClient();

// Use exactly like http.Client
final response = await client.get(Uri.parse('https://api.example.com/users'));

2b. Use DummyDioInterceptor (dio package)

Add the interceptor to your existing Dio instance:

import 'package:dummy_api_overlay/dummy_api_overlay.dart';

final dio = Dio();
dio.interceptors.add(DummyDioInterceptor());

// Use dio as normal
final response = await dio.get('https://api.example.com/users');

---

Usage

1. Run your app in debug mode.
2. Tap the floating API button (bottom-right, draggable).
3. Tap Add Rule and fill in:
   • HTTP method (GET, POST, etc., or ANY)
   • URL pattern (e.g. /users, https://api.example.com/users, or a regex)
   • Status code (e.g. 200, 404)
   • Response body (JSON)
4. Enable the rule and tap Create Rule.
5. Any matching request from DummyHttpClient or DummyDioInterceptor will now return your mock response instead of hitting the real API.

---

URL pattern matching

Patterns are matched in order:

Pattern example	Matches
https://api.example.com/users	Exact URL only
/users	Any URL containing /users
api.example.com	Any URL containing that host
.*\/users\/\d+	Regex — any URL like /users/123

Invalid regex patterns fall back to substring matching — no crashes.

---

Parameters

DummyApiOverlay

Parameter	Type	Default	Description
child	Widget	required	Your app widget
enabled	bool	kDebugMode	Show/hide the overlay button
navigatorKey	GlobalKey<NavigatorState>?	null	Shared navigator key for route pushing
buttonInitialOffset	Offset?	bottom-right	Initial position of the FAB

---

Disable in production

The overlay is off by default in release builds (enabled: kDebugMode). To explicitly disable:

DummyApiOverlay(
  enabled: false, // always off
  navigatorKey: _navigatorKey,
  child: child!,
)

---

License

MIT — see LICENSE.