retrofit 1.0.1

  • Readme
  • Changelog
  • Example
  • Installing
  • 95

Retrofit For Dart #

CircleCI Build Status Build Status

retrofit.dart is a type conversion dio client generator using source_gen and inspired by Chopper and Retrofit.

Usage #

Generator #

Add the generator to your dev dependencies

dependencies:
  retrofit: any
  logger: any  #for logging purpose

dev_dependencies:
  retrofit_generator: any
  build_runner: any

Define and Generate your API #

import 'package:json_annotation/json_annotation.dart';
import 'package:retrofit/retrofit.dart';
import 'package:dio/dio.dart';

part 'example.g.dart';

@RestApi(baseUrl: "https://5d42a6e2bc64f90014a56ca0.mockapi.io/api/v1/")
abstract class RestClient {
  factory RestClient(Dio dio) = _RestClient;

  @GET("/tasks")
  Future<List<Task>> getTasks();
}

@JsonSerializable()
class Task {
  String id;
  String name;
  String avatar;
  String createdAt;

  Task({this.id, this.name, this.avatar, this.createdAt});

  factory Task.fromJson(Map<String, dynamic> json) => _$TaskFromJson(json);
  Map<String, dynamic> toJson() => _$TaskToJson(this);
}

then run the generator

# dart
pub run build_runner build

# flutter	
flutter pub run build_runner build

Use it #

import 'package:logger/logger.dart';
import 'package:retrofit_example/example.dart';
import 'package:dio/dio.dart';

final logger = Logger();
void main(List<String> args) {
  final dio = Dio();   // Provide a dio instance
  dio.options.headers["Demo-Header"] = "demo header";   // config your dio headers globally
  dio.options.headers["Content-Type"] = "application/json";
  final client = RestClient(dio);
  
  client.getTasks().then((it) => logger.i(it));

More #

Type Conversion #

Before you use the type conversion, please make sure that a factory Task.fromJson(Map<String, dynamic> json) must be provided for each model class. json_serializable is the recommanded to be used as the serialization tool.

...
@GET("/tasks")
  Future<List<Task>> getTasks();
}

@JsonSerializable()
class Task {
  String name;
  Task({this.name});
  factory Task.fromJson(Map<String, dynamic> json) => _$TaskFromJson(json);
}

HTTP Methods #

The HTTP methods in the below sample are supported.

  @GET("/tasks/{id}")
  Future<Task> getTask(@Path("id") String id);

  @PATCH("/tasks/{id}")
  Future<Task> updateTaskPart(
      @Path() String id, @Body() Map<String, dynamic> map);

  @PUT("/tasks/{id}")
  Future<Task> updateTask(@Path() String id, @Body() Task task);

  @DELETE("/tasks/{id}")
  Future<void> deleteTask(@Path() String id);

  @POST("/tasks")
  Future<Task> createTask(@Body() Task task);

HTTP Header #

  • Add a HTTP header from the parameter of the method

      @GET("/tasks")
      Future<Task> getTasks(@Header("Content-Type") String contentType );
    
  • Add staitc HTTP headers

      @GET("/tasks")
      @Headers(<String, dynamic>{
          "Content-Type" : "application/json",
          "Custom-Header" : "Your header"
      })
      Future<Task> getTasks();
    

Error Handling #

catchError(Object) should be used for capturing the exception and failed response. You can get the detailed response info from DioError.response.

 client.getTask("2").then((it){
   logger.i(it);
 }).catchError((Object obj) {
    // non-200 error goes here.
    switch (obj.runtimeType) {
      case DioError:
        // Here's the sample to get the failed response error code and message
        final res = (obj as DioError).response;
        logger.e("Got error : ${res.statusCode} -> ${res.statusMessage}");
        break;
      default:
    }
  });

}

Changelog #

1.0.0 #

  • Support dio 3.0

0.6.3 #

  • Added autoCastResponse option to RestApi and all Method annotations (default : true)
  • Added auto_cast_response to builder options.
    • Users can specify this in build.yaml as global default

      targets:
        $default:
          sources: ['lib/**']
          builders:
            retrofit_generator|retrofit:
              enabled: true
              options:
                auto_cast_response: true
      
      

0.6.2 #

  • fix: fix bad cast exception (#47)
  • add CancelToken, SendProgress, and ReceiveProgress (#46)

0.6.0 #

  • [BREAKING CHANGE] only works dart 2.2.2 and above
  • Added support to multiple clients with different base urls.

0.5.0 #

  • Fixed analysis report use retrofit.dart instead of http.dart and dio.dart to import classes

0.4.3 #

  • Updated docs and sample code

0.2.3 #

  • Added optional parameter fileName in @Field annotation for custom file name

0.2.2 #

  • add example

0.2.0 #

  • Added @Extra to pass extra options to dio requests, response, transformer and interceptors.

    Example :

    @http.POST('/path/')
    @dio.Extra({'my_key':'my_value'})
    Future<String>> myMethod();
    
  • Fixed general dart style and code conventions

  • Automatically null check with ArgumentError.checkNotNull for required parameters

  • Now SuperClasses can use forwarding/redirecting constructors instead of static instance() method

    Example :

    @RestApi(baseUrl: "https://httpbin.org/")
    abstract class RestClient {
        /// Forwarding constructor
        factory RestClient([Dio dio]) = _RestClient;
    }
    

0.1.0 #

  • fix health issues

0.0.1 #

  • init

example/lib/example.dart

import 'package:json_annotation/json_annotation.dart';
import 'package:retrofit/retrofit.dart';
import 'package:dio/dio.dart' hide Headers;
import 'dart:io';

part 'example.g.dart';

@RestApi(baseUrl: "https://5d42a6e2bc64f90014a56ca0.mockapi.io/api/v1/")
abstract class RestClient {
  factory RestClient(Dio dio) = _RestClient;

  @GET("/tasks")
  Future<List<Task>> getTasks();

  @GET("/tasks/{id}")
  Future<Task> getTask(@Path("id") String id);

  @PATCH("/tasks/{id}")
  Future<Task> updateTaskPart(
      @Path() String id, @Body() Map<String, dynamic> map);

  @PUT("/tasks/{id}")
  Future<Task> updateTask(@Path() String id, @Body() Task task);

  @DELETE("/tasks/{id}")
  Future<void> deleteTask(@Path() String id);

  @POST("/tasks")
  Future<Task> createTask(@Body() Task task);

  @POST("http://httpbin.org/post")
  Future<void> createNewTaskFromFile(@Field() File file);

  @Headers(<String, String>{"accept": "image/jpeg"})
  @GET("http://httpbin.org/image/jpeg")
  @DioResponseType(ResponseType.bytes)
  Future<List<int>> getFile();
}

@JsonSerializable()
class Task {
  String id;
  String name;
  String avatar;
  String createdAt;

  Task({this.id, this.name, this.avatar, this.createdAt});

  factory Task.fromJson(Map<String, dynamic> json) => _$TaskFromJson(json);
  Map<String, dynamic> toJson() => _$TaskToJson(this);
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  retrofit: ^1.0.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:retrofit/retrofit.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
91
Health:
Code health derived from static analysis. [more]
97
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
95
Learn more about scoring.

We analyzed this package on Oct 9, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.5.1
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:retrofit/retrofit.dart.

Health suggestions

Fix lib/http.dart. (-2.96 points)

Analysis of lib/http.dart reported 6 hints, including:

line 57 col 26: Use = to separate a named parameter from its default value.

line 75 col 48: Use = to separate a named parameter from its default value.

line 82 col 49: Use = to separate a named parameter from its default value.

line 89 col 56: Use = to separate a named parameter from its default value.

line 96 col 54: Use = to separate a named parameter from its default value.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.2.2 <3.0.0
dio ^3.0.1 3.0.3
meta ^1.1.6 1.1.7
Transitive dependencies
charcode 1.1.2
collection 1.14.12
http_parser 3.1.3
path 1.6.4
source_span 1.5.5
string_scanner 1.0.5
term_glyph 1.1.0
typed_data 1.1.6