[1.x] Deprecate Authorization helpers in Faraday::Connection

.rubocop_todo.yml

@@ -14,7 +14,7 @@ Metrics/AbcSize:
 # Offense count: 5
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 250
+  Max: 256
 
 # Offense count: 15
 # Configuration parameters: IgnoredMethods.

docs/middleware/request/authentication.md

@@ -9,22 +9,38 @@ top_name: Back to Middleware
 top_link: ./list
 ---
 
-Basic and Token authentication are handled by Faraday::Request::BasicAuthentication
-and Faraday::Request::TokenAuthentication respectively.
-These can be added as middleware manually or through the helper methods.
+The `Faraday::Request::Authorization` middleware allows you to automatically add an `Authorization` header
+to your requests. It also features 2 specialised sub-classes that provide useful extra features for Basic Authentication
+and Token Authentication requests.
+
+### Any Authentication
+
+The generic `Authorization` middleware allows you to add any type of Authorization header.
+
+```ruby
+Faraday.new(...) do |conn|
+  conn.request :authorization, 'Bearer', 'authentication-token'
+end
+```
 
 ### Basic Authentication
 
+`BasicAuthentication` adds a 'Basic' type Authorization header to a Faraday request.
+
 ```ruby
 Faraday.new(...) do |conn|
-  conn.basic_auth('username', 'password')
+  conn.request :basic_auth, 'username', 'password'
 end
 ```
 
 ### Token Authentication
 
+`TokenAuthentication` adds a 'Token' type Authorization header to a Faraday request.
+You can optionally provide a hash of `options` that will be appended to the token.
+This is not used anymore in modern web and have been replaced by Bearer tokens.
+
 ```ruby
 Faraday.new(...) do |conn|
-  conn.token_auth('authentication-token')
+  conn.request :token_auth, 'authentication-token', **options
 end
 ```

lib/faraday/connection.rb

@@ -297,6 +297,11 @@ def #{method}(url = nil, body = nil, headers = nil, &block)
     #
     # @return [void]
     def basic_auth(login, pass)
+      warn <<~TEXT
+        WARNING: `Faraday::Connection#basic_auth` is deprecated; it will be removed in version 2.0.
+        While initializing your connection, use `#request(:basic_auth, ...)` instead.
+        See https://lostisland.github.io/faraday/middleware/authentication for more usage info.
+      TEXT
       set_authorization_header(:basic_auth, login, pass)
     end
 
@@ -314,6 +319,11 @@ def basic_auth(login, pass)
     #
     # @return [void]
     def token_auth(token, options = nil)
+      warn <<~TEXT
+        WARNING: `Faraday::Connection#token_auth` is deprecated; it will be removed in version 2.0.
+        While initializing your connection, use `#request(:token_auth, ...)` instead.
+        See https://lostisland.github.io/faraday/middleware/authentication for more usage info.
+      TEXT
       set_authorization_header(:token_auth, token, options)
     end
 
@@ -336,6 +346,11 @@ def token_auth(token, options = nil)
     #
     # @return [void]
     def authorization(type, token)
+      warn <<~TEXT
+        WARNING: `Faraday::Connection#authorization` is deprecated; it will be removed in version 2.0.
+        While initializing your connection, use `#request(:authorization, ...)` instead.
+        See https://lostisland.github.io/faraday/middleware/authentication for more usage info.
+      TEXT
       set_authorization_header(:authorization, type, token)
     end