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 #

Run your app in debug mode.
Tap the floating API button (bottom-right, draggable).
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)
Enable the rule and tap Create Rule.
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 #