my_api_client 1.3.1 → 2.0.0

data/README.jp.md

@@ -1,785 +0,0 @@
-[![CircleCI](https://circleci.com/gh/ryz310/my_api_client.svg?style=svg)](https://circleci.com/gh/ryz310/my_api_client) [![Gem Version](https://badge.fury.io/rb/my_api_client.svg)](https://badge.fury.io/rb/my_api_client) [![Maintainability](https://api.codeclimate.com/v1/badges/861a2c8f168bbe995107/maintainability)](https://codeclimate.com/github/ryz310/my_api_client/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/861a2c8f168bbe995107/test_coverage)](https://codeclimate.com/github/ryz310/my_api_client/test_coverage) [![Dependabot Status](https://api.dependabot.com/badges/status?host=github&repo=ryz310/my_api_client)](https://dependabot.com)
-
-# MyApiClient
-
-MyApiClient は API リクエストクラスを作成するための汎用的な機能を提供します。[Sawyer](https://github.com/lostisland/sawyer) や [Faraday](https://github.com/lostisland/faraday) をベースにエラーハンドリングの機能を強化した構造になっています。
-
-ただし、 Sawyer はダミーデータの作成が難しかったり、他の gem で競合することがよくあるので、将来的には依存しないように変更していくかもしれません。
-
-また、 Ruby on Rails で利用することを想定してますが、それ以外の環境でも動作するように作っています。不具合などあれば Issue ページからご報告下さい。
-
-[toc]
-
-## Supported Versions
-
-- Ruby 3.1, 3.2, 3.3
-- Rails 6.1, 7.0, 7.1, 7.2
-
-## Installation
-
-`my_api_client` を Gemfile に追加して下さい:
-
-```ruby
-gem 'my_api_client'
-```
-
-Ruby on Rails を利用している場合は `generator` 機能を利用できます。
-
-```sh
-$ rails g api_client path/to/resource get:path/to/resource --endpoint https://example.com
-
-create  app/api_clients/application_api_client.rb
-create  app/api_clients/path/to/resource_api_client.rb
-invoke  rspec
-create    spec/api_clients/path/to/resource_api_client_spec.rb
-```
-
-## Usage
-
-### Basic
-
-最もシンプルな利用例を以下に示します。
-
-```ruby
-class ExampleApiClient < MyApiClient::Base
-  endpoint 'https://example.com/v1'
-
-  attr_reader :access_token
-
-  def initialize(access_token:)
-    @access_token = access_token
-  end
-
-  # GET https://example.com/v1/users
-  #
-  # @return [Sawyer::Resource] HTTP resource parameter
-  def get_users
-    get 'users', headers: headers, query: { key: 'value' }
-  end
-
-  # POST https://example.com/v1/users
-  #
-  # @param name [String] Username which want to create
-  # @return [Sawyer::Resource] HTTP resource parameter
-  def post_user(name:)
-    post 'users', headers: headers, body: { name: name }
-  end
-
-  private
-
-  def headers
-    {
-      'Content-Type': 'application/json;charset=UTF-8',
-      'Authorization': "Bearer #{access_token}",
-    }
-  end
-end
-
-api_clinet = ExampleApiClient.new(access_token: 'access_token')
-api_clinet.get_users #=> #<Sawyer::Resource>
-```
-
-クラス定義の最初に記述される `endpoint` にはリクエスト URL の共通部分を定義します。後述の各メソッドで後続の path を定義しますが、上記の例だと `get 'users'` と定義すると、 `GET https://example.com/v1/users` というリクエストが実行されます。
-
-次に、 `#initialize` を定義します。上記の例のように Access Token や API Key などを設定することを想定します。必要なければ定義の省略も可能です。
-
-続いて、 `#get_users` や `#post_user` を定義します。メソッド名には API のタイトルを付けると良いと思います。メソッド内部で `#get` や `#post` を呼び出していますが、これがリクエスト時の HTTP Method になります。他にも `#patch` `#put` `#delete` が利用可能です。
-
-### Pagination
-
-API の中にはレスポンスに結果の続きを取得するための URL を含んでいるものがあります。
-
-MyApiClient では、このような API を enumerable に扱うための `#pageable_get` というメソッドを用意しています。以下に例を示します。
-
-```ruby
-class MyPaginationApiClient < ApplicationApiClient
-  endpoint 'https://example.com/v1'
-
-  # GET pagination?page=1
-  def pagination
-    pageable_get 'pagination', paging: '$.links.next', headers: headers, query: { page: 1 }
-  end
-
-  private
-
-  def headers
-    { 'Content-Type': 'application/json;charset=UTF-8' }
-  end
-end
-```
-
-上記の例の場合、最初に `GET https://example.com/v1/pagination?page=1` に対してリクエストが実行され、続けてレスポンス JSON の `$.link.next` に含まれる URL に対して enumerable にリクエストを実行します。
-
-例えば以下のようなレスポンスであれば、`$.link.next` は `"https://example.com/pagination?page=3"` を示します。
-
-```json
-{
-  "links": {
-    "next": "https://example.com/pagination?page=3",
-    "previous": "https://example.com/pagination?page=1"
-  },
-  "page": 2
-}
-```
-
-そして `#pageable_get` は [Enumerator::Lazy](https://docs.ruby-lang.org/ja/latest/class/Enumerator=3a=3aLazy.html) を返すので、 `#each` や `#next` を実行することで次の結果を取得できます。
-
-```ruby
-api_clinet = MyPaginationApiClient.new
-api_clinet.pagination.each do |response|
-  # Do something.
-end
-
-result = api_clinet.pagination
-result.next # => 1st page result
-result.next # => 2nd page result
-result.next # => 3rd page result
-```
-
-なお、`#each` はレスポンスに含まれる `paging` の値が `nil` になるまで繰り返されるのでご注意ください。例えば `#take` と組み合わせることでページネーションの上限を設定できます。
-
-`#pageable_get` の alias として `#pget` も利用可能です。
-
-```ruby
-# GET pagination?page=1
-def pagination
-  pget 'pagination', paging: '$.links.next', headers: headers, query: { page: 1 }
-end
-```
-
-### Error handling
-
-`my_api_client` ではレスポンスの内容によって例外を発生させるエラーハンドリングを定義できます。ここでは例として前述のコードにエラーハンドリングを定義しています。
-
-```ruby
-class ExampleApiClient < MyApiClient::Base
-  endpoint 'https://example.com'
-
-  error_handling status_code: 400..499,
-                 raise: MyApiClient::ClientError
-
-  error_handling status_code: 500..599, raise: MyApiClient::ServerError do |_params, logger|
-    logger.warn 'Server error occurred.'
-  end
-
-  error_handling json: { '$.errors.code': 10..19 },
-                 raise: MyApiClient::ClientError,
-                 with: :my_error_handling
-
-  # Omission...
-
-  private
-
-  # @param params [MyApiClient::Params::Params] HTTP reqest and response params
-  # @param logger [MyApiClient::Request::Logger] Logger for a request processing
-  def my_error_handling(params, logger)
-    logger.warn "Response Body: #{params.response.body.inspect}"
-  end
-end
-```
-
-一つずつ解説していきます。まず、以下のように `status_code` を指定するものについて。
-
-```ruby
-error_handling status_code: 400..499, raise: MyApiClient::ClientError
-```
-
-これは `ExampleApiClient` からのリクエスト全てにおいて、レスポンスのステータスコードが `400..499` であった場合に `MyApiClient::ClientError` が例外として発生するようになります。 `ExampleApiClient` を継承したクラスにもエラーハンドリングは適用されます。ステータスコードのエラーハンドリングは親クラスで定義すると良いと思います。
-
-なお、 `status_code` には `Integer` `Range` `Regexp` が指定可能です。
-
-`raise` には `MyApiClient::Error` を継承したクラスが指定可能です。`my_api_client` で標準で定義しているエラークラスについては以下のソースコードをご確認下さい。 `raise` を省略した場合は `MyApiClient::Error` を発生するようになります。
-
-https://github.com/ryz310/my_api_client/blob/master/lib/my_api_client/errors
-
-次に、 `block` を指定する場合について。
-
-```ruby
-error_handling status_code: 500..599, raise: MyApiClient::ServerError do |_params, logger|
-  logger.warn 'Server error occurred.'
-end
-```
-
-上記の例であれば、ステータスコードが `500..599` の場合に `MyApiClient::ServerError` を発生させる前に `block` の内容が実行れます。引数の `params` にはリクエスト情報とレスポンス情報が含まれています。`logger` はログ出力用インスタンスですが、このインスタンスを使ってログ出力すると、以下のようにリクエスト情報がログ出力に含まれるようになり、デバッグの際に便利です。
-
-```text
-API request `GET https://example.com/path/to/resouce`: "Server error occurred."
-```
-
-`json` には `Hash` の Key に [JSONPath](https://goessner.net/articles/JsonPath/) を指定して、レスポンス JSON から任意の値を取得し、 Value とマッチするかどうかでエラーハンドリングできます。Value には `String` `Integer` `Range` `Regexp` が指定可能です。上記の場合であれば、以下のような JSON にマッチします。
-
-```ruby
-error_handling json: { '$.errors.code': 10..19 }, with: :my_error_handling
-```
-
-```json
-{
-  "erros": {
-    "code": 10,
-    "message": "Some error has occurred."
-  }
-}
-```
-
-`headers` には `Hash` の Key に レスポンスのヘッダーキーを指定して、 Value とマッチするかどうかでエラーハンドリングできます。Value には `String` `Regexp` が指定可能です。
-
-```ruby
-error_handling headers: { 'www-authenticate': /invalid token/ }, with: :my_error_handling
-```
-
-上記の場合であれば、以下のような レスポンスヘッダー にマッチします。
-
-```text
-cache-control: no-cache, no-store, max-age=0, must-revalidate
-content-type: application/json
-www-authenticate: Bearer error="invalid_token", error_description="invalid token"
-content-length: 104
-```
-
-`with` にはインスタンスメソッド名を指定することで、エラーを検出した際、例外を発生させる前に任意のメソッドを実行させることができます。メソッドに渡される引数は `block` 定義の場合と同じく `params` と `logger` です。なお、 `block` と `with` は同時には利用できません。
-
-```ruby
-# @param params [MyApiClient::Params::Params] HTTP req and res params
-# @param logger [MyApiClient::Request::Logger] Logger for a request processing
-def my_error_handling(params, logger)
-  logger.warn "Response Body: #{params.response.body.inspect}"
-end
-```
-
-#### Default error handling
-
-`my_api_client` では、標準でステータスコード 400 ~ 500 番台のレスポンスを例外として処理するようにしています。ステータスコードが 400 番台場合は `MyApiClient::ClientError`、 500 番台の場合は `MyApiClient::ServerError` を継承した例外クラスが raise されます。
-
-また、 `MyApiClient::NetworkError` に対しても標準で `retry_on` が定義されています。
-
-いずれも override 可能ですので、必要に応じて `error_handling` を定義して下さい。
-
-以下のファイルで定義しています。
-
-https://github.com/ryz310/my_api_client/blob/master/lib/my_api_client/default_error_handlers.rb
-
-#### Symbol を利用する
-
-```ruby
-error_handling json: { '$.errors.code': :negative? }
-```
-
-実験的な機能ですが、`status` や `json` の Value に `Symbol` を指定することで、結果値に対してメソッド呼び出しを行い、結果を判定させる事ができます。上記の場合、以下のような JSON にマッチします。なお、対象 Object に `#negative?` が存在しない場合はメソッドは呼び出されません。
-
-```json
-{
-  "erros": {
-    "code": -1,
-    "message": "Some error has occurred."
-  }
-}
-```
-
-#### forbid_nil
-
-```ruby
-error_handling status_code: 200, json: :forbid_nil
-```
-
-一部のサービスではサーバーから何らかの Response Body が返ってくる事を期待しているにも関わらず、空の結果が結果が返ってくるというケースがあるようです。こちらも実験的な機能ですが、そういったケースを検出するために `json: :forbid_nil` オプションを用意しました。通常の場合、Response Body が空の場合はエラー判定をしませんが、このオプションを指定するとエラーとして検知する様になります。正常応答が空となる API も存在するので、誤検知にご注意下さい。
-
-#### MyApiClient::Params::Params
-
-WIP
-
-#### MyApiClient::Error
-
-API リクエストのレスポンスが `error_handling` で定義した matcher に合致した場合、 `raise` で指定した例外処理が発生します。この例外クラスは `MyApiClient::Error` を継承している必要があります。
-
-この例外クラスには `#params` というメソッドが存在し、リクエストやレスポンスのパラメータを参照することが出来ます。
-
-```ruby
-begin
-  api_client.request
-rescue MyApiClient::Error => e
-  e.params.inspect
-  # => {
-  #      :request=>"#<MyApiClient::Params::Request#inspect>",
-  #      :response=>"#<Sawyer::Response#inspect>",
-  #    }
-end
-```
-
-#### Bugsnag breadcrumbs
-
-[Bugsnag-Ruby v6.11.0](https://github.com/bugsnag/bugsnag-ruby/releases/tag/v6.11.0) 以降を利用している場合は [breadcrumbs 機能](https://docs.bugsnag.com/platforms/ruby/other/#logging-breadcrumbs) が自動的にサポートされます。この機能によって `MyApiClient::Error` 発生時に内部で `Bugsnag.leave_breadcrumb` が呼び出され、 Bugsnag のコンソールからエラー発生時のリクエスト情報、レスポンス情報などが確認できるようになります。
-
-### Retry
-
-次に `MyApiClient` が提供するリトライ機能についてご紹介致します。
-
-```ruby
-class ExampleApiClient < MyApiClient::Base
-  endpoint 'https://example.com'
-
-  retry_on MyApiClient::NetworkError, wait: 0.1.seconds, attempts: 3
-  retry_on MyApiClient::ApiLimitError, wait: 30.seconds, attempts: 3
-
-  error_handling json: { '$.errors.code': 20 }, raise: MyApiClient::ApiLimitError
-end
-```
-
-API リクエストを何度も実行していると回線の不調などによりネットワークエラーが発生する事があります。長時間ネットワークが使えなくなるケースもありますが、瞬間的なエラーであるケースも多々あります。 `MyApiClient` ではネットワーク系の例外はまとめて `MyApiClient::NetworkError` として `raise` されます。この例外の詳細は後述しますが、 `retry_on` を利用する事で、 `ActiveJob` のように任意の例外処理を補足して、一定回数、一定の期間を空けて API リクエストをリトライさせる事ができます。
-
-なお、 `retry_on MyApiClient::NetworkError` は標準実装されているため、特別に定義せずとも自動的に適用されます。 `wait` や `attempts` に任意の値を設定したい場合のみ定義してご利用ください。
-
-ただし、 `ActiveJob` とは異なり同期処理でリトライするため、ネットワークの瞬断に備えたリトライ以外ではあまり使う機会はないのではないかと思います。上記の例のように API Rate Limit に備えてリトライするケースもあるかと思いますが、こちらは `ActiveJob` で対応した方が良いかもしれません。
-
-ちなみに一応 `discard_on` も実装していますが、作者自身が有効な用途を見出せていないので、詳細は割愛します。良い利用方法があれば教えてください。
-
-#### 便利な使い方
-
-`error_handling` に `retry` オプションを付与する事で `retry_on` の定義を省略できます。
-例えば以下の 2 つのコードは同じ意味になります。
-
-```ruby
-retry_on MyApiClient::ApiLimitError, wait: 30.seconds, attempts: 3
-error_handling json: { '$.errors.code': 20 },
-               raise: MyApiClient::ApiLimitError
-```
-
-```ruby
-error_handling json: { '$.errors.code': 20 },
-               raise: MyApiClient::ApiLimitError,
-               retry: { wait: 30.seconds, attempts: 3 }
-```
-
-`retry_on` で `wait` や `attempts` を指定する必要がない場合は `retry: true` という記述で動作します。
-
-```ruby
-error_handling json: { '$.errors.code': 20 },
-               raise: MyApiClient::ApiLimitError,
-               retry: true
-```
-
-`retry` オプションを使用する際は以下の点に注意が必要です。
-
-- `error_handling` に `raise` オプションの指定が必須となります。
-- Block を使った `error_handling` の定義は禁止されます。
-
-#### MyApiClient::NetworkError
-
-前述の通りですが、 `MyApiClient` ではネットワーク系の例外はまとめて `MyApiClient::NetworkError` として `raise` されます。他の例外と同じく `MyApiClient::Error` を親クラスとしています。 `MyApiClient::NetworkError` として扱われる例外クラスの一覧は `MyApiClient::NETWORK_ERRORS` で参照できます。また、元となった例外は `#original_error` で参照できます。
-
-```ruby
-begin
-  api_client.request
-rescue MyApiClient::NetworkError => e
-  e.original_error # => #<Net::OpenTimeout>
-  e.params.response # => nil
-end
-```
-
-なお、通常の例外はリクエストの結果によって発生しますが、この例外はリクエスト中に発生するため、例外インスタンスにレスポンスパラメータは含まれません。
-
-### Timeout
-
-WIP
-
-### Logger
-
-WIP
-
-## One request for one class
-
-多くの場合、同一ホストの API は リクエストヘッダーやエラー情報が同じ構造になっているため、上記のように一つのクラス内に複数の API を定義する設計が理にかなっていますが、 API 毎に個別に定義したい場合は、以下のように 1 つのクラスに 1 の API という構造で設計することも可能です。
-
-```ruby
-class ExampleApiClient < MyApiClient::Base
-  endpoint 'https://example.com'
-
-  error_handling status_code: 400..599
-
-  attr_reader :access_token
-
-  def initialize(access_token:)
-    @access_token = access_token
-  end
-
-  private
-
-  def headers
-    {
-      'Content-Type': 'application/json;charset=UTF-8',
-      'Authorization': "Bearer #{access_token}",
-    }
-  end
-end
-
-class GetUsersApiClient < ExampleApiClient
-  error_handling json: { '$.errors.code': 10 }, raise: MyApiClient::ClientError
-
-  # GET https://example.com/users
-  #
-  # @return [Sawyer::Resource] HTTP resource parameter
-  def request
-    get 'users', query: { key: 'value' }, headers: headers
-  end
-end
-
-class PostUserApiClient < ExampleApiClient
-  error_handling json: { '$.errors.code': 10 }, raise: MyApiClient::ApiLimitError
-
-  # POST https://example.com/users
-  #
-  # @param name [String] Username which want to create
-  # @return [Sawyer::Resource] HTTP resource parameter
-  def request(name:)
-    post 'users', headers: headers, body: { name: name }
-  end
-end
-```
-
-## RSpec
-
-### Setup
-
-RSpec を使ったテストをサポートしています。
-以下のコードを `spec/spec_helper.rb` (または `spec/rails_helper.rb`) に追記して下さい。
-
-```ruby
-require 'my_api_client/rspec'
-```
-
-### Testing
-
-以下のような `ApiClient` を定義しているとします。
-
-```ruby
-class ExampleApiClient < MyApiClient::Base
-  endpoint 'https://example.com/v1'
-
-  error_handling status_code: 200, json: { '$.errors.code': 10 },
-                 raise: MyApiClient::ClientError
-
-  attr_reader :access_token
-
-  def initialize(access_token:)
-    @access_token = access_token
-  end
-
-  # GET https://example.com/v1/users
-  def get_users(condition:)
-    get 'users', headers: headers, query: { search: condition }
-  end
-
-  private
-
-  def headers
-    {
-      'Content-Type': 'application/json;charset=UTF-8',
-      'Authorization': "Bearer #{access_token}",
-    }
-  end
-end
-```
-
-通常の場合 `ApiClient` を新たに定義した際にテストすべき項目が 2 つあります。
-
-1. 指定したエンドポイントに対して、任意のパラメータを使ったリクエストが実行されること
-2. 特定のレスポンスに対して適切にエラーハンドリングが実行されること
-
-`my_api_client` ではこれらをテストするための Custom Matcher を用意しています。
-
-#### 1. 指定したエンドポイントに対して、任意のパラメータを使ったリクエストが実行されること
-
-例えば上述の `#get_users` の内部では、入力引数を用いて検索クエリが組み立てられていたり、 Header に `access_token` を利用したりしています。これらの値が正しくリクエストに用いられているかどうかのテストが必要となります。
-
-この場合 `request_to` と `with` という Custom Matcher を利用することで簡単にテストを記述することが出来ます。 `expect` にはブロック `{}` を指定する必要がある点にご注意ください。他にも `with` には `body` というキーワード引数も指定できます。
-
-```ruby
-RSpec.describe ExampleApiClient, type: :api_client do
-  let(:api_client) { described_class.new(access_token: 'access token') }
-  let(:headers) do
-    {
-      'Content-Type': 'application/json;charset=UTF-8',
-      'Authorization': 'Bearer access token',
-    }
-  end
-
-  describe '#get_users' do
-    it do
-      expect { api_client.get_users(condition: 'condition') }
-        .to request_to(:get, 'https://example.com/v1/users')
-        .with(headers: headers, query: { condition: 'condition' })
-    end
-  end
-end
-```
-
-#### 2. 特定のレスポンスに対して適切にエラーハンドリングが実行されること
-
-次に `error_handling` についてのテストも記述していきます。ここではレスポンスのステータスコードが `200` かつ Body に `'$.errors.code': 10` という値が含まれていた場合は `MyApiClient::ClientError` を `raise` する、というエラーハンドリングが定義されています。
-
-ここでは `be_handled_as_an_error` と `when_receive` という Custom Matcher を利用します。ここでも `expect` にはブロック `{}` を指定する必要がある点にご注意ください。
-
-`be_handled_as_an_error` の引数には期待する例外クラスを指定します。 `when_receive` にはリクエスト結果としてどのような値が返ってきたのかを指定します。
-
-なお、 `error_handling` で例外を発生させないケースは現在想定していないため、これ以外の Custom Matcher は定義されていません。何かユースケースがあれば教えて下さい。
-
-```ruby
-it do
-  expect { api_client.get_users(condition: 'condition') }
-    .to be_handled_as_an_error(MyApiClient::ClientError)
-    .when_receive(status_code: 200, body: { errors: { code: 10 } }.to_json)
-end
-```
-
-また、以下のように正常なレスポンスが返ってきた時に誤ってエラーハンドリングされていないかをテストすることもできます。
-
-```ruby
-it do
-  expect { api_client.get_users(condition: 'condition') }
-    .not_to be_handled_as_an_error(MyApiClient::ClientError)
-    .when_receive(status_code: 200, body: { users: { id: 1 } }.to_json)
-end
-```
-
-##### `retry_on` を定義している場合
-
-以下のように `retry_on` を API Client に定義している場合:
-
-```ruby
-class ExampleApiClient < MyApiClient::Base
-  endpoint 'https://example.com'
-
-  error_handling json: { '$.errors.code': 20 }, raise: MyApiClient::ApiLimitError
-  retry_on MyApiClient::ApiLimitError, wait: 30.seconds, attempts: 3
-end
-```
-
-`after_retry` と `times` という Custom Matcher を利用することが出来ます。
-
-```ruby
-it do
-  expect { api_client.get_users(condition: 'condition') }
-    .to be_handled_as_an_error(MyApiClient::ApiLimitError)
-    .after_retry(3).times
-    .when_receive(status_code: 200, body: { errors: { code: 20 } }.to_json)
-end
-```
-
-### Stubbing
-
-#### `response` option
-
-以下のような `ApiClient` を定義しているとします。
-
-```ruby
-class ExampleApiClient < MyApiClient::Base
-  endpoint 'https://example.com'
-
-  def request(user_id:)
-    get "users/#{user_id}"
-  end
-end
-```
-
-`stub_api_client_all` や `stub_api_client` を使うことで、 `ExampleApiClient#request` をスタブ化することができます。これで `#request` を実行してもリアルな HTTP リクエストが実行されなくなります。
-
-```ruby
-stub_api_client_all(
-  ExampleApiClient,
-  request: { response: { id: 12345 } }
-)
-
-response = ExampleApiClient.new.request(user_id: 1)
-response.id # => 12345
-```
-
-`response` は省略することも可能です。
-
-```ruby
-stub_api_client_all(
-  ExampleApiClient,
-  request: { id: 12345 }
-)
-
-response = ExampleApiClient.new.request(user_id: 1)
-response.id # => 12345
-```
-
-#### Proc
-
-リクスエストパラメータを使ったレスポンスを返すようにスタブ化したい場合は、 `Proc` を利用することで実現できます。
-
-```ruby
-stub_api_client_all(
-  ExampleApiClient,
-  request: ->(params) { { id: params[:user_id] } }
-)
-
-response = ExampleApiClient.new.request(user_id: 1)
-response.id # => 1
-```
-
-#### Return value of `#stub_api_client_all` and `#stub_api_client`
-
-`#stub_api_client_all` や `#stub_api_client` の戻り値はスタブ化した API Client のスタブオブジェクトです。`receive` や `have_received` を使ったテストを書きたい場合は、これらの値を利用すると良いでしょう。
-
-```ruby
-def execute_api_request
-  ExampleApiClient.new.request(user_id: 1)
-end
-
-api_clinet = stub_api_client_all(ExampleApiClient, request: nil)
-execute_api_request
-expect(api_client).to have_received(:request).with(user_id: 1)
-```
-
-#### `raise` option
-
-例外が発生する場合のテストを書きたい場合は、 `raise` オプションを利用することができます。
-
-```ruby
-def execute_api_request
-  ExampleApiClient.new.request(user_id: 1)
-end
-
-stub_api_client_all(ExampleApiClient, request: { raise: MyApiClient::Error })
-expect { execute_api_request }.to raise_error(MyApiClient::Error)
-```
-
-なお、発生した例外に含まれるレスポンスパラメータやステータスコードもスタブ化したい場合は、 `response` オプションと同時に指定することが可能です。
-
-```ruby
-stub_api_client_all(
-  ExampleApiClient,
-  request: {
-    raise: MyApiClient::Error,
-    response: { message: 'error' },
-    status_code: 429
-  }
-)
-
-begin
-  ExampleApiClient.new.request(user_id: 1)
-rescue MyApiClient::Error => e
-  response_body = e.params.response.data.to_h
-  expect(response_body).to eq(message: 'error')
-  status_code = e.params.response.status
-  expect(status_code).to eq(429)
-end
-```
-
-#### `pageable` option
-
-`#pageable_get` (`#pget`) を使った実装用に `pageable` というオプションが利用できます。
-`pageable` に設定する値は `Enumerable` である必要があります。
-
-```ruby
-stub_api_client_all(
-  MyPaginationApiClient,
-  pagination: {
-    pageable: [
-      { page: 1 },
-      { page: 2 },
-      { page: 3 },
-    ],
-  }
-)
-
-MyPaginationApiClient.new.pagination.each do |response|
-  response.page #=> 1, 2, 3
-end
-```
-
-なお、 `Enumerable` の各値にはここまで紹介した `response`, `raise`, `Proc` など全てのオプションが利用可能です。
-
-```ruby
-stub_api_client_all(
-  MyPaginationApiClient,
-  pagination: {
-    pageable: [
-      { response: { page: 1 } },
-      { page: 2 },
-      ->(params) { { page: 3, user_id: params[:user_id] } },
-      { raise: MyApiClient::ClientError::IamTeapot },
-    ],
-  }
-)
-```
-
-また、 `Enumerator` を使えば無限に続くページネーションを定義することもできます。
-
-```ruby
-stub_api_client_all(
-  MyPaginationApiClient,
-  pagination: {
-    pageable: Enumerator.new do |y|
-      loop.with_index(1) do |_, i|
-        y << { page: i }
-      end
-    end,
-  }
-)
-```
-
-## Deployment
-
-この gem のリリースには [gem_comet](https://github.com/ryz310/gem_comet) を利用しています。
-`gem_comet` の README.md にも使い方が載っていますが、備忘録のため、こちらにもリリースフローを記載しておきます。
-
-### Preparement
-
-以下のコマンドで `.envrc` を作成し、 `GITHUB_ACCESS_TOKEN` を設定します。
-
-```sh
-$ cp .envrc.skeleton .envrc
-```
-
-以下のコマンドで `gem_comet` をインストールします。
-
-```sh
-$ gem install gem_comet
-```
-
-### USAGE
-
-以下のコマンドで、最後のリリースから現在までに merge した PR の一覧を確認できます。
-
-```sh
-$ gem_comet changelog
-```
-
-以下のコマンドで gem のリリースを実行します。
-`{VERSION}` には新しく付与するバージョン番号を指定します。
-
-```sh
-$ gem_comet release {VERSION}
-```
-
-実行すると、 https://github.com/ryz310/my_api_client/pulls に以下のような PR が作成されます。
-
-- [Update v0\.16\.1](https://github.com/ryz310/my_api_client/pull/297)
-- [Release v0\.16\.1](https://github.com/ryz310/my_api_client/pull/298)
-
-まず、 `Update v{VERSION}` という PR から merge に取り掛かります。
-
-PR のコメントにも TODO が記載されていますが、まず、バージョン番号が正しく採番されているかを確認します。
-
-See: [314a4c0](https://github.com/ryz310/my_api_client/pull/297/commits/314a4c06f66324ce77b640b1ee8db5c84ee038a2)
-
-次に `CHANGELOG.md` を編集して、 CHANGELOG を見やすく整理します。
-
-See: [33a2d17](https://github.com/ryz310/my_api_client/pull/297/commits/33a2d1703c773813c837e74ee3181906b2f2e502)
-
-これらが整ったら、 `Update v{VERSION}` を merge します。
-
-これでリリース準備が整ったので、`Release v{VERSION}` の merge に取り掛かります。
-
-この PR にこれからリリースする gem に対する変更が全て載っています。
-変更内容の最終確認をして、 CI も通ったことを確認したら `Release v{VERSION}` を merge します。
-
-あとは Circle CI 側で gem のリリースが自動実行されるので、暫く待ちましょう。
-
-お疲れさまでした :tea:
-
-## Contributing
-
-不具合の報告や Pull Request を歓迎しています。OSS という事で自分はなるべく頑張って英語を使うようにしていますが、日本語での報告でも大丈夫です :+1: