implementing-openapi-in-dart

Implementing OpenAPI 3.0 in Dart

Given an OpenAPI 3.0 spec, implement a type-safe Dart API layer with:

• Freezed (or Equatable) for models
• Dio for HTTP with interceptors and error handling
• json_serializable for JSON serialisation

Process

1. Read the OpenAPI spec — parse components/schemas for models, paths for endpoints.
2. Map schemas → Dart models (Freezed or Equatable — see Model Strategy).
3. Map paths → Dio service methods.
4. Add a repository layer that wraps the service.
5. Wire error handling via DioException → domain ApiError.

---

Dependencies

dependencies:
  dio: ^5.9.2
  freezed_annotation: ^3.1.0   # if using Freezed
  json_annotation: ^4.11.0
  equatable: ^2.0.5             # if using Equatable

dev_dependencies:
  build_runner: ^2.14.1
  freezed: ^3.2.5               # if using Freezed
  json_serializable: ^6.13.1

---

Directory Structure

lib/
└── data/
    ├── network/
    │   ├── dio_client.dart          # Dio instance + interceptors
    │   ├── api_error.dart           # global error model
    │   └── services/
    │       └── product_service.dart # one file per resource tag
    └── models/
        ├── product.dart
        └── ...

---

Dio Client Setup

import 'package:dio/dio.dart';

Dio createDioClient({required String baseUrl, String? accessToken}) {
  final dio = Dio(BaseOptions(
    baseUrl: baseUrl,
    connectTimeout: const Duration(seconds: 10),
    receiveTimeout: const Duration(seconds: 10),
    headers: {'Content-Type': 'application/json'},
  ));

  dio.interceptors.add(InterceptorsWrapper(
    onRequest: (options, handler) {
      if (accessToken != null) {
        options.headers['Authorization'] = 'Bearer $accessToken';
      }
      handler.next(options);
    },
    onError: (error, handler) {
      // Convert DioException to domain ApiError before propagating
      handler.next(error);
    },
  ));

  return dio;
}

---

Model Strategy