my_api_client 1.3.1 → 2.0.0

data/README.md

@@ -1,23 +1,23 @@
-[![CircleCI](https://circleci.com/gh/ryz310/my_api_client.svg?style=svg)](https://circleci.com/gh/ryz310/my_api_client)
+[![CI](https://github.com/ryz310/my_api_client/actions/workflows/ci.yml/badge.svg)](https://github.com/ryz310/my_api_client/actions/workflows/ci.yml)
 [![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)
+[![Maintainability](https://qlty.sh/gh/ryz310/projects/my_api_client/maintainability.svg)](https://qlty.sh/gh/ryz310/projects/my_api_client)
+[![Code Coverage](https://qlty.sh/gh/ryz310/projects/my_api_client/coverage.svg)](https://qlty.sh/gh/ryz310/projects/my_api_client)
 ![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/ryz310/my_api_client)
 
-日本語ドキュメントは [こちら](README.jp.md)
-
 # MyApiClient
 
-This gem is an API client builder. It provides generic functionality for creating API request classes. It has a structure based on [Sawyer](https://github.com/lostisland/sawyer) and [Faraday](https://github.com/lostisland/faraday) with enhanced error handling functions.
+This gem is an API client builder that provides generic functionality for defining API request classes. Its architecture is based on [Sawyer](https://github.com/lostisland/sawyer) and [Faraday](https://github.com/lostisland/faraday), with enhanced error-handling features.
+
+Sawyer can be difficult for generating dummy data and may conflict with other gems in some cases, so this project may reduce direct Sawyer dependency in the future.
 
-It is supposed to be used in Ruby on Rails, but it is made to work in other environments. If you have any problems, please report them from the Issue page.
+It is primarily designed for Ruby on Rails, but it also works in other environments. If you find any issues, please report them on the Issues page.
 
 [toc]
 
 ## Supported Versions
 
-- Ruby 3.1, 3.2, 3.3
-- Rails 6.1, 7.0, 7.1, 7.2
+- Ruby 3.2, 3.3, 3.4, 4.0
+- Rails 7.2, 8.0, 8.1
 
 ## Installation
 
@@ -27,7 +27,7 @@ Add this line to your application's Gemfile:
 gem 'my_api_client'
 ```
 
-If you are using Ruby on Rails, you can use the `generator` function.
+If you are using Ruby on Rails, you can use the generator.
 
 ```sh
 $ rails g api_client path/to/resource get:path/to/resource --endpoint https://example.com
@@ -63,7 +63,7 @@ class ExampleApiClient < MyApiClient::Base
 
   # POST https://example.com/v1/users
   #
-  # @param name [String] Username which want to create
+  # @param name [String] Username to create
   # @return [Sawyer::Resource] HTTP resource parameter
   def post_user(name:)
     post 'users', headers: headers, body: { name: name }
@@ -79,21 +79,21 @@ class ExampleApiClient < MyApiClient::Base
   end
 end
 
-api_clinet = ExampleApiClient.new(access_token: 'access_token')
-api_clinet.get_users #=> #<Sawyer::Resource>
+api_client = ExampleApiClient.new(access_token: 'access_token')
+api_client.get_users #=> #<Sawyer::Resource>
 ```
 
-The `endpoint` defines the intersection of the request URL. Each method described below defines a subsequent path. In the above example, `get 'users'` will request to `GET https://example.com/v1/users`.
+`endpoint` defines the base URL for requests. Each method then adds a relative path. In the example above, `get 'users'` sends `GET https://example.com/v1/users`.
 
-Next, define `#initialize`. Suppose you want to set an Access Token, API Key, etc. as in the example above. You can omit the definition if you don't need it.
+Next, define `#initialize` to set values such as an access token or API key. You can omit it if you do not need any instance state.
 
-Then define `#get_users` and `#post_user`. It's a good idea to give the method name the title of the API. I'm calling `#get` and `#post` inside the method, which is the HTTP Method at the time of the request. You can also use `#patch` `#put` `#delete`.
+Then define methods such as `#get_users` and `#post_user`. Inside those methods, call HTTP helpers like `#get` and `#post`. You can also use `#patch`, `#put`, and `#delete`.
 
 ### Pagination
 
-Some APIs include a URL in the response to get the continuation of the result.
+Some APIs include a URL for the next page in the response.
 
-MyApiClient provides a method called `#pageable_get` to handle such APIs as enumerable. An example is shown below:
+MyApiClient provides `#pageable_get` to treat such APIs as an enumerable. An example is shown below:
 
 ```ruby
 class MyPaginationApiClient < ApplicationApiClient
@@ -112,9 +112,9 @@ class MyPaginationApiClient < ApplicationApiClient
 end
 ```
 
-In the above example, the request is first made for `GET https://example.com/v1/pagination?page=1`, followed by the URL contained in the response JSON `$.link.next`. Make a request to enumerable.
+In the example above, the first request is `GET https://example.com/v1/pagination?page=1`. It then continues requesting the URL in `$.links.next` from each response.
 
-For example, in the following response, `$.link.next` indicates `"https://example.com/pagination?page=3"`:
+For example, in the response below, `$.links.next` points to `"https://example.com/pagination?page=3"`:
 
 ```json
 {
@@ -126,15 +126,15 @@ For example, in the following response, `$.link.next` indicates `"https://exampl
 }
 ```
 
-`#pageable_get` returns [Enumerator::Lazy](https://docs.ruby-lang.org/ja/latest/class/Enumerator=3a=3aLazy.html), so you can get the following result by `#each` or `#next`:
+`#pageable_get` returns [Enumerator::Lazy](https://docs.ruby-lang.org/ja/latest/class/Enumerator=3a=3aLazy.html), so you can iterate using `#each` or `#next`:
 
 ```ruby
-api_clinet = MyPaginationApiClient.new
-api_clinet.pagination.each do |response|
+api_client = MyPaginationApiClient.new
+api_client.pagination.each do |response|
   # Do something.
 end
 
-result = api_clinet.pagination
+result = api_client.pagination
 result.next # => 1st page result
 result.next # => 2nd page result
 result.next # => 3rd page result
@@ -153,7 +153,7 @@ end
 
 ### Error handling
 
-MyApiClient allows you to define error handling that raises an exception depending on the content of the response. Here, as an example, error handling is defined in the above code:
+MyApiClient lets you define error handling rules that raise exceptions based on response content. For example:
 
 ```ruby
 class ExampleApiClient < MyApiClient::Base
@@ -174,7 +174,7 @@ class ExampleApiClient < MyApiClient::Base
 
   private
 
-  # @param params [MyApiClient::Params::Params] HTTP reqest and response params
+  # @param params [MyApiClient::Params::Params] HTTP request 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}"
@@ -182,19 +182,19 @@ class ExampleApiClient < MyApiClient::Base
 end
 ```
 
-I will explain one by one. First, about the one that specifies `status_code` as follows:
+Let's go through each option. First, this rule checks `status_code`:
 
 ```ruby
 error_handling status_code: 400..499, raise: MyApiClient::ClientError
 ```
 
-This will cause `MyApiClient::ClientError` to occur as an exception if the status code of the response is `400..499` for all requests from `ExampleApiClient`. Error handling also applies to classes that inherit from `ExampleApiClient`.
+This raises `MyApiClient::ClientError` when the response status code is in `400..499` for requests from `ExampleApiClient`. Error handling rules are also inherited by child classes.
 
-Note that `Integer` `Range`, and `Regexp` can be specified for `status_code`.
+You can specify `Integer`, `Range`, or `Regexp` for `status_code`.
 
-A class that inherits `MyApiClient::Error` can be specified for `raise`. Please check [here](https://github.com/ryz310/my_api_client/blob/master/lib/my_api_client/errors) for the error class defined as standard in `my_api_client`. If `raise` is omitted, `MyApiClient::Error` will be raised.
+A class inheriting from `MyApiClient::Error` can be specified for `raise`. See [here](https://github.com/ryz310/my_api_client/blob/master/lib/my_api_client/errors) for built-in error classes. If `raise` is omitted, `MyApiClient::Error` is raised.
 
-Next, about the case of specifying `block`:
+Next, here is an example using a block:
 
 ```ruby
 error_handling status_code: 500..599, raise: MyApiClient::ServerError do |_params, logger|
@@ -202,38 +202,38 @@ error_handling status_code: 500..599, raise: MyApiClient::ServerError do |_param
 end
 ```
 
-In the above example, if the status code is `500..599`, the contents of `block` will be executed before raising `MyApiClient::ServerError`. The argument `params` contains request and response information.
+In this example, when the status code is `500..599`, the block runs before `MyApiClient::ServerError` is raised. The `params` argument includes both request and response information.
 
-`logger` is an instance for log output. If you log output using this instance, the request information will be included in the log output as shown below, which is convenient for debugging:
+`logger` is a request-scoped logger. If you log with this instance, request information is automatically included, which is useful for debugging:
 
 ```text
-API request `GET https://example.com/path/to/resouce`: "Server error occurred."
+API request `GET https://example.com/path/to/resource`: "Server error occurred."
 ```
 
 ```ruby
 error_handling json: { '$.errors.code': 10..19 }, with: :my_error_handling
 ```
 
-For `json`, specify [JSONPath](https://goessner.net/articles/JsonPath/) for the Key of `Hash`, get an arbitrary value from the response JSON, and check whether it matches value. You can handle errors. You can specify `String` `Integer` `Range` and `Regexp` for value.
+For `json`, use [JSONPath](https://goessner.net/articles/JsonPath/) as the hash key, extract values from response JSON, and match them against expected values. You can specify `String`, `Integer`, `Range`, or `Regexp` as matcher values.
 
-In the above case, it matches JSON as below:
+In this case, it matches JSON such as:
 
 ```json
 {
-  "erros": {
+  "errors": {
     "code": 10,
     "message": "Some error has occurred."
   }
 }
 ```
 
-For `headers`, specify response header for the Key of `Hash`, get an arbitrary value from the response header, and check whether it matches value. You can handle errors. You can specify `String` and `Regexp` for value.
+For `headers`, specify a response-header key and match its value. You can specify `String` or `Regexp` as matcher values.
 
 ```ruby
 error_handling headers: { 'www-authenticate': /invalid token/ }, with: :my_error_handling
 ```
 
-In the above case, it matches response header as below:
+In this case, it matches response headers such as:
 
 ```text
 cache-control: no-cache, no-store, max-age=0, must-revalidate
@@ -242,7 +242,7 @@ www-authenticate: Bearer error="invalid_token", error_description="invalid token
 content-length: 104
 ```
 
-By specifying the instance method name in `with`, when an error is detected, any method can be executed before raising an exception. The arguments passed to the method are `params` and `logger` as in the `block` definition. Note that `block` and` with` cannot be used at the same time.
+By specifying an instance method name in `with`, you can run arbitrary logic before raising an exception. The method receives `params` and `logger`, just like a block. Note that `block` and `with` cannot be used together.
 
 ```ruby
 # @param params [MyApiClient::Params::Params] HTTP req and res params
@@ -254,7 +254,7 @@ end
 
 #### Default error handling
 
-In MyApiClient, the response of status code 400 ~ 500 series is handled as an exception by default. If the status code is in the 400s, an exception class that inherits `MyApiClient::ClientError` is raised, and in the 500s, an exception class that inherits `MyApiClient::ServerError` is raised.
+By default, MyApiClient treats 4xx and 5xx responses as exceptions. In the 4xx range, it raises an exception class inheriting from `MyApiClient::ClientError`; in the 5xx range, it raises one inheriting from `MyApiClient::ServerError`.
 
 Also, `retry_on` is defined by default for `MyApiClient::NetworkError`.
 
@@ -268,7 +268,7 @@ They are defined [here](https://github.com/ryz310/my_api_client/blob/master/lib/
 error_handling json: { '$.errors.code': :negative? }
 ```
 
-Although it is an experimental function, by specifying `Symbol` for value of `status` or `json`, you can call a method for the result value and judge the result. In the above case, it matches the following JSON. If `#negative?` does not exist in the target object, the method will not be called.
+This is an experimental feature. By specifying a `Symbol` as the value for `status` or `json`, MyApiClient calls that method on the extracted value and uses the result for matching. In the example above, it matches the following JSON. If `#negative?` does not exist on the target object, the method is not called.
 
 #### forbid_nil
 
@@ -276,15 +276,37 @@ Although it is an experimental function, by specifying `Symbol` for value of `st
 error_handling status_code: 200, json: :forbid_nil
 ```
 
-It seems that some services expect an empty Response Body to be returned from the server, but an empty result is returned. This is also an experimental feature, but we have provided the `json: :forbid_nil` option to detect such cases. Normally, if the response body is empty, no error judgment is made, but if this option is specified, it will be detected as an error. Please be careful about false positives because some APIs have an empty normal response.
+Some services expect a non-empty response body but occasionally receive an empty one. This experimental option, `json: :forbid_nil`, helps detect that case. Normally, an empty response body is not treated as an error, but with this option it is. Be careful of false positives, because some APIs intentionally return empty responses.
 
 #### MyApiClient::Params::Params
 
-WIP
+`MyApiClient::Params::Params` is a value object that combines request and response details.
+An instance of this class is passed to error handlers (`block`/`with`) and is also available from `MyApiClient::Error#params`.
+
+- `#request`: `MyApiClient::Params::Request` (method, URL, headers, and body)
+- `#response`: `Sawyer::Response` (or `nil` for network errors)
+
+It also provides `#metadata` (`#to_bugsnag` alias), which merges request/response data into a single hash for logging and error reporting.
+
+```ruby
+begin
+  api_client.request
+rescue MyApiClient::Error => e
+  e.params.metadata
+  # => {
+  #      request_line: "GET https://example.com/v1/users?search=foo",
+  #      request_headers: { "Authorization" => "Bearer token" },
+  #      response_status: 429,
+  #      response_headers: { "content-type" => "application/json" },
+  #      response_body: { errors: [{ code: 20 }] },
+  #      duration: 0.123
+  #    }
+end
+```
 
 #### MyApiClient::Error
 
-If the response of the API request matches the matcher defined in `error_handling`, the exception handling specified in `raise` will occur. This exception class must inherit `MyApiClient::Error`.
+If an API response matches a rule defined in `error_handling`, the exception class specified in `raise` is triggered. This exception class must inherit from `MyApiClient::Error`.
 
 This exception class has a method called `#params`, which allows you to refer to request and response parameters.
 
@@ -302,11 +324,11 @@ end
 
 #### Bugsnag breadcrumbs
 
-If you are using [Bugsnag-Ruby v6.11.0](https://github.com/bugsnag/bugsnag-ruby/releases/tag/v6.11.0) or later, [breadcrumbs function](https://docs. bugsnag.com/platforms/ruby/other/#logging-breadcrumbs) is automatically supported. With this function, `Bugsnag.leave_breadcrumb` is called internally when `MyApiClient::Error` occurs, and you can check the request information, response information, etc. when an error occurs from the Bugsnag console.
+If you are using [Bugsnag-Ruby v6.19.0](https://github.com/bugsnag/bugsnag-ruby/releases/tag/v6.19.0) or later, the [breadcrumbs feature](https://docs.bugsnag.com/platforms/ruby/other/#logging-breadcrumbs) is supported automatically. When `MyApiClient::Error` occurs, `Bugsnag.leave_breadcrumb` is called internally, so you can inspect request and response details in the Bugsnag console.
 
 ### Retry
 
-Next, I would like to introduce the retry function provided by MyApiClient.
+Next, let's look at retry support in MyApiClient.
 
 ```ruby
 class ExampleApiClient < MyApiClient::Base
@@ -319,13 +341,13 @@ class ExampleApiClient < MyApiClient::Base
 end
 ```
 
-If the API request is executed many times, a network error may occur due to a line malfunction. In some cases, the network will be unavailable for a long time, but in many cases it will be a momentary error. In MyApiClient, network exceptions are collectively raised as `MyApiClient::NetworkError`. The details of this exception will be described later, but by using `retry_on`, it is possible to supplement arbitrary exception handling like `ActiveJob` and retry the API request a certain number of times and after a certain period of time.
+When an API request is executed many times, network errors can occur. Sometimes the network is unavailable for a long time, but often the error is temporary. In MyApiClient, network-related exceptions are wrapped as `MyApiClient::NetworkError`. Using `retry_on`, you can handle such exceptions and retry requests with configurable wait time and attempt count, similar to `ActiveJob`.
 
-Note that `retry_on MyApiClient::NetworkError` is implemented as standard, so it will be applied automatically without any special definition. Please define and use it only when you want to set an arbitrary value for `wait` or `attempts`.
+`retry_on MyApiClient::NetworkError` is enabled by default, so you do not need to define it unless you want custom `wait` or `attempts` values.
 
-However, unlike `ActiveJob`, it retries in synchronous processing, so I think that there is not much opportunity to use it other than retrying in case of a momentary network interruption. As in the above example, there may be cases where you retry in preparation for API Rate Limit, but it may be better to handle this with `ActiveJob`.
+Unlike `ActiveJob`, retries are performed synchronously. In practice, this is most useful for short-lived network interruptions. You can also retry for API rate limits as in the example above, but handling that with `ActiveJob` may be a better fit depending on your workload.
 
-By the way, `discard_on` is also implemented, but since the author himself has not found an effective use, I will omit the details. Please let me know if there is a good way to use it.
+`discard_on` is also implemented, but details are omitted here because a strong use case has not been identified yet.
 
 #### Convenient usage
 
@@ -344,7 +366,7 @@ error_handling json: { '$.errors.code': 20 },
                retry: { wait: 30.seconds, attempts: 3 }
 ```
 
-If you do not need to specify `wait` or` attempts` in `retry_on`, it works with `retry: true`:
+If you do not need to specify `wait` or `attempts` in `retry_on`, you can use `retry: true`:
 
 ```ruby
 error_handling json: { '$.errors.code': 20 },
@@ -359,7 +381,7 @@ Keep the following in mind when using the `retry` option:
 
 #### MyApiClient::NetworkError
 
-As mentioned above, in MyApiClient, network exceptions are collectively `raised` as `MyApiClient::NetworkError`. Like the other exceptions, it has `MyApiClient::Error` as its parent class. A list of exception classes treated as `MyApiClient::NetworkError` can be found in `MyApiClient::NETWORK_ERRORS`. You can also refer to the original exception with `#original_error`:
+As mentioned above, MyApiClient wraps network exceptions as `MyApiClient::NetworkError`. Like other client errors, its parent class is `MyApiClient::Error`. The list of wrapped exception classes is available in `MyApiClient::NETWORK_ERRORS`. You can inspect the original exception via `#original_error`:
 
 ```ruby
 begin
@@ -370,15 +392,99 @@ rescue MyApiClient::NetworkError => e
 end
 ```
 
-Note that a normal exception is raised depending on the result of the request, but since this exception is raised during the request, the exception instance does not include the response parameter.
+Unlike normal API errors that are raised after receiving a response, this exception is raised during request execution. Therefore, the exception instance does not include response parameters.
 
 ### Timeout
 
-WIP
+You can configure HTTP timeout values per API client class:
+
+```ruby
+class ApplicationApiClient < MyApiClient::Base
+  http_open_timeout 2.seconds
+  http_read_timeout 3.seconds
+end
+```
+
+- `http_open_timeout`: maximum wait time to open a connection
+- `http_read_timeout`: maximum wait time for each HTTP read
+
+Internally, these are passed to Faraday request options as `open_timeout` and `timeout`.
+If a timeout occurs, it is wrapped and raised as `MyApiClient::NetworkError`.
 
 ### Logger
 
-WIP
+Each API client class has a configurable logger (`self.logger`).
+By default, MyApiClient uses `Logger.new($stdout)`, and in Rails apps you typically set:
+
+```ruby
+class ApplicationApiClient < MyApiClient::Base
+  self.logger = Rails.logger
+end
+```
+
+MyApiClient wraps this logger with `MyApiClient::Request::Logger` and prefixes messages with request information:
+
+```text
+API request `GET https://example.com/v1/users`: "Start"
+API request `GET https://example.com/v1/users`: "Duration 100.0 msec"
+API request `GET https://example.com/v1/users`: "Success (200)"
+```
+
+On failure, it logs:
+
+```text
+API request `GET https://example.com/v1/users`: "Failure (Net::OpenTimeout)"
+```
+
+## One request for one class
+
+In many cases, APIs on the same host share request headers and error structures, so defining multiple endpoints in one class is practical. If you prefer API-level separation, you can also use a "one class per API" design:
+
+```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 to create
+  # @return [Sawyer::Resource] HTTP resource parameter
+  def request(name:)
+    post 'users', headers: headers, body: { name: name }
+  end
+end
+```
 
 ## RSpec
 
@@ -393,7 +499,7 @@ require 'my_api_client/rspec'
 
 ### Testing
 
-Suppose you have defined a `ApiClient` like this:
+Suppose you have defined an `ApiClient` like this:
 
 ```ruby
 class ExampleApiClient < MyApiClient::Base
@@ -424,21 +530,251 @@ class ExampleApiClient < MyApiClient::Base
 end
 ```
 
-WIP
+When you define a new API client, these are the two main test targets:
+
+1. It sends the expected HTTP request (method, URL, headers/query/body)
+2. It handles error responses as expected (`error_handling`)
+
+MyApiClient provides custom matchers for both.
+
+#### 1. Request assertion (`request_to` + `with`)
+
+Use `request_to` to assert method/URL and `with` to assert `headers`, `query`, or `body`.
+`expect` must receive a block.
+
+```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: { search: 'condition' })
+    end
+  end
+end
+```
+
+#### 2. Error handling assertion (`be_handled_as_an_error` + `when_receive`)
+
+Use `be_handled_as_an_error` to assert the raised error class, and `when_receive` to provide mock response input (`status_code`, `headers`, `body`).
+
+```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
+```
+
+You can also assert that a response is *not* handled as an error:
+
+```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
+```
+
+If the client has `retry_on`, you can assert retry count with `after_retry(...).times`:
+
+```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
 
-WIP
+Use `stub_api_client_all` or `stub_api_client` to stub API client methods without real HTTP.
+
+#### `response` option
+
+```ruby
+class ExampleApiClient < MyApiClient::Base
+  endpoint 'https://example.com'
+
+  def request(user_id:)
+    get "users/#{user_id}"
+  end
+end
+
+stub_api_client_all(
+  ExampleApiClient,
+  request: { response: { id: 12_345 } }
+)
+
+response = ExampleApiClient.new.request(user_id: 1)
+response.id # => 12345
+```
+
+`response` can be omitted as shorthand:
+
+```ruby
+stub_api_client_all(
+  ExampleApiClient,
+  request: { id: 12_345 }
+)
+```
+
+#### Proc response
+
+You can generate response data from request arguments:
+
+```ruby
+stub_api_client_all(
+  ExampleApiClient,
+  request: ->(params) { { id: params[:user_id] } }
+)
+```
+
+#### Return value of `stub_api_client_all` / `stub_api_client`
+
+Both methods return a spy object, so you can assert received calls:
+
+```ruby
+def execute_api_request
+  ExampleApiClient.new.request(user_id: 1)
+end
+
+api_client = stub_api_client_all(ExampleApiClient, request: nil)
+execute_api_request
+expect(api_client).to have_received(:request).with(user_id: 1)
+```
+
+#### `raise` option
+
+To test error paths, use the `raise` option:
+
+```ruby
+stub_api_client_all(ExampleApiClient, request: { raise: MyApiClient::Error })
+expect { ExampleApiClient.new.request(user_id: 1) }.to raise_error(MyApiClient::Error)
+```
+
+You can combine `raise`, `response`, and `status_code`:
+
+```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
+  e.params.response.data.to_h # => { message: "error" }
+  e.params.response.status    # => 429
+end
+```
+
+#### `pageable` option
+
+For `#pageable_get` (`#pget`), you can stub page-by-page responses:
+
+```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
+```
+
+Each page entry supports the same options (`response`, `raise`, `Proc`, etc.).  
+You can also pass an `Enumerator` for endless pagination stubs.
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### Integration Specs With Real HTTP
+
+The integration specs under `spec/integrations/api_clients/` call the local `my_api` Rails server via HTTP.
+
+Run with Docker Compose:
+
+```sh
+docker compose up -d --build my_api
+docker compose run --rm test bundle exec rspec
+docker compose down --volumes --remove-orphans
+```
+
+Run only integration specs:
+
+```sh
+docker compose up -d --build my_api
+docker compose run --rm test bundle exec rspec spec/integrations/api_clients
+docker compose down --volumes --remove-orphans
+```
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Deployment
+
+This project uses [gem_comet](https://github.com/ryz310/gem_comet) for release automation.
+
+### Preparation
+
+Create `.envrc` and set `GITHUB_ACCESS_TOKEN`:
+
+```sh
+cp .envrc.skeleton .envrc
+```
+
+Install `gem_comet`:
+
+```sh
+gem install gem_comet
+```
+
+### Usage
+
+Check PRs merged since the previous release:
+
+```sh
+gem_comet changelog
+```
+
+Start a release with a new version:
+
+```sh
+gem_comet release {VERSION}
+```
+
+This creates two PRs:
+
+- `Update v{VERSION}`
+- `Release v{VERSION}`
+
+Merge `Update v{VERSION}` first after checking version bump and polishing `CHANGELOG.md`.  
+Then verify `Release v{VERSION}` (including CI) and merge it to publish the gem.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/my_api_client. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/ryz310/my_api_client. Reports in Japanese are also welcome. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 
@@ -446,4 +782,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the MyApiClient project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/my_api_client/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the MyApiClient project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ryz310/my_api_client/blob/master/CODE_OF_CONDUCT.md).