diff --git a/chopper/README.md b/chopper/README.md index 9f401e6d..ec24a6bb 100644 --- a/chopper/README.md +++ b/chopper/README.md @@ -2,21 +2,35 @@ [![pub package](https://img.shields.io/pub/v/chopper.svg)](https://pub.dartlang.org/packages/chopper) [![Build Status](https://travis-ci.com/lejard-h/chopper.svg?branch=master)](https://travis-ci.org/lejard-h/chopper) [![codecov](https://codecov.io/gh/lejard-h/chopper/branch/master/graph/badge.svg)](https://codecov.io/gh/lejard-h/chopper) -[Documentations](https://hadrien-lejard.gitbook.io/chopper) +[**Documentation**](https://hadrien-lejard.gitbook.io/chopper) -## Installation +## Adding Chopper to your project + +In your project's `pubspec.yaml` file, + +* Add *chopper*'s latest version to your *dependencies*. +* Add `build_runner: ^1.10.3` to your *dev_dependencies*. + * *build_runner* may already be in your *dev_dependencies* depending on your project setup and other dependencies. +* Add *chopper_generator*'s latest version to your *dev_dependencies*. ```yaml # pubspec.yaml dependencies: - chopper: ^2.0.0 + chopper: ^ dev_dependencies: - build_runner: ^1.0.0 - chopper_generator: ^2.0.0 + build_runner: ^1.10.3 + chopper_generator: ^ ``` +Latest versions: + +* *chopper* ![pub package](https://img.shields.io/pub/v/chopper.svg) +* *chopper_generator* ![pub package](https://img.shields.io/pub/v/chopper_generator.svg) + +## Documentation + * [Getting started](getting-started.md) * [Converters](converters/converters.md) * [Interceptors](interceptors.md) @@ -27,5 +41,5 @@ dev_dependencies: * [Built Value](https://github.com/lejard-h/chopper/blob/master/example/bin/main_built_value.dart) * [Angular](https://github.com/lejard-h/chopper/blob/master/example/web/main.dart) -## [Issue Tracker](https://github.com/lejard-h/chopper/issues) +## If you encounter any issues, or need a feature implemented, please visit [Chopper's Issue Tracker](https://github.com/lejard-h/chopper/issues). diff --git a/chopper/lib/src/base.dart b/chopper/lib/src/base.dart index 8f59e761..6747f52b 100644 --- a/chopper/lib/src/base.dart +++ b/chopper/lib/src/base.dart @@ -39,7 +39,7 @@ class ChopperClient { /// The [ErrorConverter] that handles response transformation before the /// response interceptors are called, but only on error responses - /// \(statusCode < 200 || statusCode >= 300\). + /// (statusCode < 200 || statusCode >= 300\). final ErrorConverter errorConverter; final Map _services = {}; diff --git a/chopper/lib/src/interceptor.dart b/chopper/lib/src/interceptor.dart index ac7257dc..15f14d13 100644 --- a/chopper/lib/src/interceptor.dart +++ b/chopper/lib/src/interceptor.dart @@ -85,7 +85,7 @@ abstract class Converter { /// \(e.g., `String` or `CustomObject)`. /// /// If `BodyType` is a `List` or a `BuiltList`, `InnerType` is the type of the - /// generic parameter \(e.g., `convertResponse, CustomObject>(response)` \). + /// generic parameter (e.g., `convertResponse, CustomObject>(response)` ). FutureOr> convertResponse( Response response, ); @@ -94,7 +94,7 @@ abstract class Converter { /// An interface for implementing error response converters. /// /// An `ErrorConverter` is called only on error responses -/// \(statusCode < 200 || statusCode >= 300\) and before any [ResponseInterceptor]s. +/// (statusCode < 200 || statusCode >= 300) and before any [ResponseInterceptor]s. abstract class ErrorConverter { /// Converts the received [Response] to a [Response] which has a body with the diff --git a/chopper/pubspec.yaml b/chopper/pubspec.yaml index 261d09db..8c9244fc 100644 --- a/chopper/pubspec.yaml +++ b/chopper/pubspec.yaml @@ -1,7 +1,7 @@ name: chopper -description: Chopper is an http client generator using source_gen and inspired from retrofit +description: Chopper is an http client generator using source_gen, inspired by Retrofit version: 3.0.6 -homepage: https://hadrien-lejard.gitbook.io/chopper +documentation: https://hadrien-lejard.gitbook.io/chopper repository: https://github.com/lejard-h/chopper author: Hadrien Lejard diff --git a/chopper_built_value/README.md b/chopper_built_value/README.md index 7afbd05a..455791c5 100644 --- a/chopper_built_value/README.md +++ b/chopper_built_value/README.md @@ -1 +1 @@ -[Chopper](https://github.com/lejard-h/chopper) is an http client generator using source_gen and inspired by Retrofit. \ No newline at end of file +[Chopper](https://github.com/lejard-h/chopper) is an http client generator using source_gen, inspired by Retrofit. \ No newline at end of file diff --git a/chopper_built_value/lib/chopper_built_value.dart b/chopper_built_value/lib/chopper_built_value.dart index 76202441..5eaf9d5f 100644 --- a/chopper_built_value/lib/chopper_built_value.dart +++ b/chopper_built_value/lib/chopper_built_value.dart @@ -3,11 +3,19 @@ import 'package:chopper/chopper.dart'; import 'package:built_collection/built_collection.dart'; import 'package:built_value/serializer.dart'; +/// A custom [Converter] and [ErrorConverter] that handles conversion for classes +/// having a serializer implementation made with the built_value package. class BuiltValueConverter implements Converter, ErrorConverter { final Serializers serializers; final JsonConverter jsonConverter = JsonConverter(); final Type errorType; + /// Builds a new BuiltValueConverter instance that uses built_value serializers defined + /// in the provided [serializers] parameter. + /// + /// If the error body cannot be converted with serializers and [errorType] is provided + /// and it's not `null`, BuiltValueConverter will try to deserialize the error body into + /// [errorType]. BuiltValueConverter(this.serializers, {this.errorType}); T _deserialize(dynamic value) { diff --git a/chopper_built_value/pubspec.yaml b/chopper_built_value/pubspec.yaml index 534101d1..25943496 100644 --- a/chopper_built_value/pubspec.yaml +++ b/chopper_built_value/pubspec.yaml @@ -1,7 +1,7 @@ name: chopper_built_value -description: Chopper is an http client generator using source_gen and inspired from retrofit +description: A built_value based Converter for Chopper. version: 0.0.6 -homepage: https://hadrien-lejard.gitbook.io/chopper +documentation: https://hadrien-lejard.gitbook.io/chopper/converters/built-value-converter repository: https://github.com/lejard-h/chopper author: Hadrien Lejard diff --git a/chopper_generator/README.md b/chopper_generator/README.md index 7afbd05a..455791c5 100644 --- a/chopper_generator/README.md +++ b/chopper_generator/README.md @@ -1 +1 @@ -[Chopper](https://github.com/lejard-h/chopper) is an http client generator using source_gen and inspired by Retrofit. \ No newline at end of file +[Chopper](https://github.com/lejard-h/chopper) is an http client generator using source_gen, inspired by Retrofit. \ No newline at end of file diff --git a/chopper_generator/pubspec.yaml b/chopper_generator/pubspec.yaml index 045785a8..62f070ac 100644 --- a/chopper_generator/pubspec.yaml +++ b/chopper_generator/pubspec.yaml @@ -1,7 +1,7 @@ name: chopper_generator -description: Chopper is an http client generator using source_gen and inspired from retrofit +description: Chopper is an http client generator using source_gen, inspired by Retrofit version: 3.0.6 -homepage: https://hadrien-lejard.gitbook.io/chopper +documentation: https://hadrien-lejard.gitbook.io/chopper repository: https://github.com/lejard-h/chopper author: Hadrien Lejard diff --git a/converters/built-value-converter.md b/converters/built-value-converter.md index 5712cbea..cc6b49dc 100644 --- a/converters/built-value-converter.md +++ b/converters/built-value-converter.md @@ -1,25 +1,29 @@ -# Built Value Converter +# BuiltValueConverter {% hint style="warning" %} Experimental {% endhint %} -Chopper converter for [built\_value](https://pub.dev/packages/built_value) serializer. +A Chopper Converter for [built\_value](https://pub.dev/packages/built_value) based serialization. ## Installation +Add the chopper_built_value package to your project's dependencies in pubspec.yaml: + ```yaml # pubspec.yaml dependencies: - chopper_build_value: ^0.0.1 + chopper_built_value: ^ ``` +The latest version is [![pub package](https://img.shields.io/pub/v/chopper_built_value.svg)](https://pub.dartlang.org/packages/chopper_built_value). + ## Getting started ### Built value -Define your models. +Define your models as you usually do with built_value. ```dart abstract class DataModel implements Built { @@ -32,7 +36,7 @@ abstract class DataModel implements Built { } ``` -Aggregate all serializers +Aggregate all serializers into a top level collection. ```dart /// Collection of generated serializers for the built_value @@ -42,11 +46,13 @@ Aggregate all serializers final Serializers serializers = _$serializers; ``` -See built\_value [documentation](https://pub.dev/packages/built_value) for more informations. +See [built\_value documentation](https://pub.dev/packages/built_value) for more information on how built_value works. -### Chopper +### Using BuiltValueConverter with Chopper -Provide serializers to the converter and to the ChopperClient. +Build a `BuiltValueConverter` by providing the `built_value` serializer collection. + +To use the created converter, pass it to `ChopperClient`'s `converter` constructor parameter. ```dart final builder = serializers.toBuilder(); @@ -60,12 +66,14 @@ final client = ChopperClient(converter: converter); #### Error converter -You can use `BuiltValueConverter` as an error converter. It will try to decode error using the `wireName` inside JSON `{"$":"ErrorModel"}` if available. +`BuiltValueConverter` is also an error converter. It will try to decode error response bodies using the `wireName` inside JSON `{"$":"ErrorModel"}`, if available. -If `wireName` is not available, you can specify the type of your error to the converter. +If `wireName` is not available, `BuiltValueConverter` will try to convert error response bodies to `errorType`, if it was provided and is not `null`. ```dart -BuiltValueConverter(jsonSerializers, errorType: ErrorModel); +final jsonSerializers = ... + +final converter = BuiltValueConverter(jsonSerializers, errorType: ErrorModel); ``` diff --git a/converters/converters.md b/converters/converters.md index 69485d6c..2bdf2a41 100644 --- a/converters/converters.md +++ b/converters/converters.md @@ -12,7 +12,7 @@ final chopper = ChopperClient( ``` {% hint style="info" %} -The `errorConverter` is called only on error responses \(statusCode < 200 \|\| statusCode >= 300\). +The `errorConverter` is called only on error responses (statusCode < 200 || statusCode >= 300). {% endhint %} ## The built-in JSON converter @@ -33,14 +33,14 @@ You can implement custom converters by implementing the `Converter` class. class MyConverter implements Converter { @override Response convertResponse(Response response) { - var body = response.body + var body = response.body; // Convert body to BodyType however you like response.copyWith(body: body); } @override Request convertRequest(Request request) { - var body = request.body + var body = request.body; // Convert body to String however you like return request.copyWith(body: body); } diff --git a/example/pubspec.yaml b/example/pubspec.yaml index fbb663fe..78eb3a70 100644 --- a/example/pubspec.yaml +++ b/example/pubspec.yaml @@ -1,7 +1,7 @@ name: chopper_example -description: Example of Chopper +description: Example usage of the Chopper package version: 0.0.1 -#homepage: https://www.example.com +documentation: https://hadrien-lejard.gitbook.io/chopper/ author: Hadrien Lejard environment: