こんにちは。エキサイトでアプリエンジニアをしている岡島です。今回は業務でChopperというライブラリを使用したので、Chopperの基礎を説明しながら、GitHubのAPIで検索結果を取得するまでを記事にしていこうと思います。GitHubのAPIの仕様については省略します。

Chopperとは

Chopperは Retrofit（Kotlin/AndroidのHTTPクライアント）のように、アノテーションを使ってAPIを定義できます。Chopper では、API 通信のコードを自動生成されるので、URL や HTTP メソッド、パラメータをアノテーションを用いて直感的に定義できるのが特徴です。

環境

dependencies:
  chopper: ^8.1.0

dev_dependencies:
  build_runner: ^2.4.9
  chopper_generator: ^8.1.0

APIサービスを定義する

lib/github_service.dartファイルを作成し、以下のコードを追加します。

import 'package:chopper/chopper.dart';

part 'github_service.chopper.dart';

@ChopperApi(baseUrl: '/search/repositories')
abstract class GithubService extends ChopperService {
  @GET()
  Future<Response> searchFlutterRepos(
    @Query('q') String query,
    @Query('per_page') int perPage,
  );

  static GithubService create([ChopperClient? client]) =>
      _$GithubService(client);
}

github_service.dartを追加したら、ターミナルで以下のコマンドを実行し、Chopperのコードを生成します。

dart run build_runner build

@ChopperApi(baseUrl: '/search/repositories')

GitHub APIのリポジトリ検索エンドポイントである /search/repositoriesを設定しています。

後述するChopperClientのbaseUrlをhttps://api.github.comに設定すると、

https://api.github.com/search/repositories

にリクエストが送信されます。

@GET()アノテーション

@GET()アノテーションを付与することで、このメソッドがGETリクエストを送信するAPIメソッドになります。 @GET, @POST, @PUT, @PATCH, @DELETE, @HEADが用意されています。

クエリパラメータの設定

@Query('q')と記述すると、クエリパラメータの設定ができます。今回の例では、queryという変数をqというパラメータ名として設定しています。

APIクライアントの初期化

続いてクライアントの初期化を行います。

  final client = ChopperClient(
    baseUrl: Uri.parse('https://api.github.com'),
    services: [GithubService.create()],
    converter: const JsonConverter(),
  );

  final service = GithubService.create(client);

baseUrlについて

baseUrlは、API通信の際にリクエストを送る「基準となるURL」を設定します。この場合、GitHub APIの基本URLであるhttps://api.github.com を指定しています。

共通のAPIのベースURLはChopperClientで設定するのが良さそうです。

services: [GithubService.create()]について

services:で指定すると、指定したGithubService.create()が使用できるようになります。

services:でGithubService.create()を登録することで、以下のようにsearchFlutterReposメソッドを呼び出すことができます。

final service = GithubService.create(client);
final response = await service.searchFlutterRepos('flutter', 10);

converter: const JsonConverter()

converterのオプションは、API のレスポンス（受信したデータ）を適切なフォーマットに変換するために使用されます。 JsonConverterを指定すると、Chopperが自動的にJSONをパースしてくれます。

検索結果を表示

以下にmain.dartの全コードを載せておきます。

void main() async {
  final client = ChopperClient(
    baseUrl: Uri.parse('https://api.github.com'),
    services: [GithubService.create()],
    converter: const JsonConverter(),
  );

  final service = GithubService.create(client);

  final response = await service.searchFlutterRepos('flutter', 10);

  if (response.isSuccessful) {
    print(response.body);
  } else {
    print('Error: ${response.statusCode}');
  }
}