📝 Updated public member documentation

Author: Guldem

lib/src/extensions/request.dart

@@ -1,9 +1,11 @@
 import 'package:chopper/chopper.dart';
 
+/// Helper extension to easily apply a authorization header to a request.
 extension ChopperRequest on Request {
-  Request addAuthorizationHeader(String token) {
-    final newHeaders = Map<String, String>.from(headers);
-    newHeaders['Authorization'] = 'Bearer $token';
-    return copyWith(headers: newHeaders);
-  }
+  /// Adds a authorization header with a bearer [token] to the request.
+  Request addAuthorizationHeader(String token) => applyHeader(
+        this,
+        'Authorization',
+        'Bearer $token',
+      );
 }

lib/src/oauth_authenticator.dart

@@ -4,20 +4,32 @@ import 'package:chopper/chopper.dart';
 import 'package:oauth_chopper/oauth_chopper.dart';
 import 'package:oauth_chopper/src/extensions/request.dart';
 
+/// Callback for error handling.
 typedef OnErrorCallback = void Function(Object, StackTrace);
 
-/// OAuthAuthenticator provides a authenticator that handles OAuth authorizations.
+/// {@template authenticator}
+/// OAuthAuthenticator provides a authenticator that handles
+/// OAuth authorizations.
 /// When the provided credentials are invalid it tries to refresh them.
-/// Can throw a exceptions if no [onError] is passed. When [onError] is passed exception will be passed to [onError]
+/// Can throw a exceptions if no [onError] is passed. When [onError] is passed
+/// exception will be passed to [onError]
+/// {@endtemplate}
 class OAuthAuthenticator extends Authenticator {
+  /// {@macro authenticator}
   OAuthAuthenticator(this.oauthChopper, this.onError);
 
+  /// Callback for error handling.
   final OnErrorCallback? onError;
+  /// The [OAuthChopper] instance to get the token from and
+  /// to refresh the token.
   final OAuthChopper oauthChopper;
 
   @override
-  FutureOr<Request?> authenticate(Request request, Response<dynamic> response,
-      [Request? originalRequest]) async {
+  FutureOr<Request?> authenticate(
+    Request request,
+    Response<dynamic> response, [
+    Request? originalRequest,
+  ]) async {
     final token = await oauthChopper.token;
     if (response.statusCode == 401 && token != null) {
       try {

lib/src/oauth_chopper.dart

@@ -8,6 +8,7 @@ import 'package:oauth_chopper/src/oauth_token.dart';
 import 'package:oauth_chopper/src/storage/memory_storage.dart';
 import 'package:oauth_chopper/src/storage/oauth_storage.dart';
 
+/// {@template oauth_chopper}
 /// OAuthChopper client for configuring OAuth authentication with [Chopper].
 ///
 /// For example:
@@ -18,7 +19,21 @@ import 'package:oauth_chopper/src/storage/oauth_storage.dart';
 ///     secret: secret,
 ///   );
 /// ```
+/// {@endtemplate}
 class OAuthChopper {
+  /// {@macro oauth_chopper}
+  OAuthChopper({
+    required this.authorizationEndpoint,
+    required this.identifier,
+    required this.secret,
+    this.endSessionEndpoint,
+
+    /// OAuth storage for storing credentials.
+    /// By default it will use a in memory storage [MemoryStorage]. For persisting the credentials implement a custom [OAuthStorage].
+    /// See [OAuthStorage] for more information.
+    OAuthStorage? storage,
+  }) : _storage = storage ?? MemoryStorage();
+
   /// OAuth authorization endpoint.
   final Uri authorizationEndpoint;
 
@@ -36,24 +51,10 @@ class OAuthChopper {
   /// See [OAuthStorage] for more information.
   final OAuthStorage _storage;
 
-  OAuthChopper({
-    required this.authorizationEndpoint,
-    required this.identifier,
-    required this.secret,
-    this.endSessionEndpoint,
-
-    /// OAuth storage for storing credentials.
-    /// By default it will use a in memory storage [MemoryStorage]. For persisting the credentials implement a custom [OAuthStorage].
-    /// See [OAuthStorage] for more information.
-    OAuthStorage? storage,
-  }) : _storage = storage ?? MemoryStorage();
-
   /// Get stored [OAuthToken].
   Future<OAuthToken?> get token async {
     final credentialsJson = await _storage.fetchCredentials();
-    return credentialsJson != null
-        ? OAuthToken.fromJson(credentialsJson)
-        : null;
+    return credentialsJson != null ? OAuthToken.fromJson(credentialsJson) : null;
   }
 
   /// Provides an [OAuthAuthenticator] instance.
@@ -75,8 +76,7 @@ class OAuthChopper {
     if (credentialsJson == null) return null;
     final credentials = Credentials.fromJson(credentialsJson);
     try {
-      final newCredentials =
-          await credentials.refresh(identifier: identifier, secret: secret);
+      final newCredentials = await credentials.refresh(identifier: identifier, secret: secret);
       await _storage.saveCredentials(newCredentials.toJson());
       return OAuthToken.fromCredentials(newCredentials);
     } on AuthorizationException {
@@ -92,8 +92,7 @@ class OAuthChopper {
   ///
   /// Throws an exception if the grant fails.
   Future<OAuthToken> requestGrant(OAuthGrant grant) async {
-    final credentials =
-        await grant.handle(authorizationEndpoint, identifier, secret);
+    final credentials = await grant.handle(authorizationEndpoint, identifier, secret);
 
     await _storage.saveCredentials(credentials);
 

lib/src/oauth_grant.dart

@@ -1,23 +1,38 @@
 import 'package:oauth2/oauth2.dart' as oauth;
 
-abstract class OAuthGrant {
+/// {@template oauth_grant}
+/// Interface for a OAuth grant.
+/// Grants are used to obtain credentials from an authorization server.
+/// {@endtemplate}
+abstract interface class OAuthGrant {
+  /// {@macro oauth_grant}
   const OAuthGrant();
 
-  Future<String> handle(
-      Uri authorizationEndpoint, String identifier, String secret);
+  /// Obtains credentials from an authorization server.
+  Future<String> handle(Uri authorizationEndpoint, String identifier, String secret);
 }
 
+/// {@template resource_owner_password_grant}
 /// Obtains credentials using a [resource owner password grant](https://tools.ietf.org/html/rfc6749#section-1.3.3).
-class ResourceOwnerPasswordGrant extends OAuthGrant {
+///
+/// This grant uses the resource owner's [username] and [password] to obtain
+/// credentials.
+/// {@endtemplate}
+class ResourceOwnerPasswordGrant implements OAuthGrant {
+  /// {@macro resource_owner_password_grant}
+  const ResourceOwnerPasswordGrant({
+    required this.username,
+    required this.password,
+  });
+
+  /// Username used for obtaining credentials.
   final String username;
-  final String password;
 
-  const ResourceOwnerPasswordGrant(
-      {required this.username, required this.password});
+  /// Password used for obtaining credentials.
+  final String password;
 
   @override
-  Future<String> handle(
-      Uri authorizationEndpoint, String identifier, String secret) async {
+  Future<String> handle(Uri authorizationEndpoint, String identifier, String secret) async {
     final client = await oauth.resourceOwnerPasswordGrant(
       authorizationEndpoint,
       username,
@@ -29,13 +44,15 @@ class ResourceOwnerPasswordGrant extends OAuthGrant {
   }
 }
 
+/// {@template client_credentials_grant}
 /// Obtains credentials using a [client credentials grant](https://tools.ietf.org/html/rfc6749#section-1.3.4).
-class ClientCredentialsGrant extends OAuthGrant {
+/// {@endtemplate}
+class ClientCredentialsGrant implements OAuthGrant {
+  /// {@macro client_credentials_grant}
   const ClientCredentialsGrant();
 
   @override
-  Future<String> handle(
-      Uri authorizationEndpoint, String identifier, String secret) async {
+  Future<String> handle(Uri authorizationEndpoint, String identifier, String secret) async {
     final client = await oauth.clientCredentialsGrant(
       authorizationEndpoint,
       identifier,
@@ -45,8 +62,11 @@ class ClientCredentialsGrant extends OAuthGrant {
   }
 }
 
+/// {@template authorization_code_grant}
 /// Obtains credentials using a [authorization code grant](https://tools.ietf.org/html/rfc6749#section-1.3.1).
-class AuthorizationCodeGrant extends OAuthGrant {
+/// {@endtemplate}
+class AuthorizationCodeGrant implements OAuthGrant {
+  /// {@macro authorization_code_grant}
   const AuthorizationCodeGrant({
     required this.tokenEndpoint,
     required this.scopes,
@@ -55,26 +75,48 @@ class AuthorizationCodeGrant extends OAuthGrant {
     required this.listen,
   });
 
+  /// A URL provided by the authorization server that this library uses to
+  /// obtain long-lasting credentials.
+  ///
+  /// This will usually be listed in the authorization server's OAuth2 API
+  /// documentation.
   final Uri tokenEndpoint;
+
+  /// The redirect URL where the resource owner will redirect to.
   final Uri redirectUrl;
+
+  /// The specific permissions being requested from the authorization server may
+  /// be specified via [scopes].
   final List<String> scopes;
+  /// Callback used for redirect the authorizationUrl given by the authorization
+  /// server.
   final Future<void> Function(Uri authorizationUri) redirect;
+  /// Callback used for listening for the redirectUrl.
   final Future<Uri> Function(Uri redirectUri) listen;
 
   @override
   Future<String> handle(
-      Uri authorizationEndpoint, String identifier, String secret) async {
+    Uri authorizationEndpoint,
+    String identifier,
+    String secret,
+  ) async {
     final grant = oauth.AuthorizationCodeGrant(
       identifier,
       authorizationEndpoint,
       tokenEndpoint,
     );
-    var authorizationUrl =
-        grant.getAuthorizationUrl(redirectUrl, scopes: scopes);
+
+    final authorizationUrl = grant.getAuthorizationUrl(
+      redirectUrl,
+      scopes: scopes,
+    );
+
     await redirect(authorizationUrl);
-    var responseUrl = await listen(redirectUrl);
-    oauth.Client client =
-        await grant.handleAuthorizationResponse(responseUrl.queryParameters);
+    final responseUrl = await listen(redirectUrl);
+
+    final oauth.Client client = await grant.handleAuthorizationResponse(
+      responseUrl.queryParameters,
+    );
 
     return client.credentials.toJson();
   }

lib/src/oauth_interceptor.dart

@@ -4,12 +4,16 @@ import 'package:chopper/chopper.dart';
 import 'package:oauth_chopper/oauth_chopper.dart';
 import 'package:oauth_chopper/src/extensions/request.dart';
 
+/// {@template oauth_interceptor}
 /// OAuthInterceptor is responsible for adding 'Authorization' header to requests.
 /// The header is only added if there is a token available. When no token is available no header is added.
 /// Its added as a Bearer token.
+/// {@endtemplate}
 class OAuthInterceptor implements RequestInterceptor {
+  /// {@macro oauth_interceptor}
   OAuthInterceptor(this.oauthChopper);
 
+  /// The [OAuthChopper] instance to get the token from.
   final OAuthChopper oauthChopper;
 
   @override

lib/src/oauth_token.dart

@@ -1,30 +1,63 @@
 import 'package:oauth2/oauth2.dart';
 
+/// {@template oauth_token}
+/// A wrapper around [Credentials] to provide a more convenient API.
+/// {@endtemplate}
 class OAuthToken {
-  final String accessToken;
-  final String? refreshToken;
-  final DateTime? expiration;
-  final String? idToken;
-
-  bool get isExpired =>
-      expiration != null && DateTime.now().isAfter(expiration!);
-
+  /// {@macro oauth_token}
   const OAuthToken._(
     this.accessToken,
     this.refreshToken,
     this.expiration,
     this.idToken,
   );
 
+  /// Creates a new instance of [OAuthToken] from a JSON string.
+  /// {@macro oauth_token}
   factory OAuthToken.fromJson(String json) {
     final credentials = Credentials.fromJson(json);
     return OAuthToken.fromCredentials(credentials);
   }
 
+  /// Creates a new instance of [OAuthToken] from [Credentials].
+  /// {@macro oauth_token}
   factory OAuthToken.fromCredentials(Credentials credentials) => OAuthToken._(
         credentials.accessToken,
         credentials.refreshToken,
         credentials.expiration,
         credentials.idToken,
       );
+
+  /// The token that is sent to the resource server to prove the authorization
+  /// of a client.
+  final String accessToken;
+
+  /// The token that is sent to the authorization server to refresh the
+  /// credentials.
+  ///
+  /// This may be `null`, indicating that the credentials can't be refreshed.
+  final String? refreshToken;
+
+  /// The date at which these credentials will expire.
+  ///
+  /// This is likely to be a few seconds earlier than the server's idea of the
+  /// expiration date.
+  final DateTime? expiration;
+
+  /// The token that is received from the authorization server to enable
+  /// End-Users to be Authenticated, contains Claims, represented as a
+  /// JSON Web Token (JWT).
+  ///
+  /// This may be `null`, indicating that the 'openid' scope was not
+  /// requested (or not supported).
+  ///
+  /// [spec]: https://openid.net/specs/openid-connect-core-1_0.html#IDToken
+  final String? idToken;
+
+  /// Whether the token is expired.
+  bool get isExpired =>
+      expiration != null &&
+      DateTime.now().isAfter(
+        expiration!,
+      );
 }

lib/src/storage/oauth_storage.dart

@@ -1,6 +1,7 @@
 import 'dart:async';
 
-abstract class OAuthStorage {
+/// Interface for storage of OAuth credentials.
+abstract interface class OAuthStorage {
   const OAuthStorage();
 
   /// Fetch stored credentials.

test/oauth_interceptor_test.dart

@@ -59,7 +59,7 @@ void main() {
     // arrange
     when(() => mockOAuthChopper.token).thenAnswer((_) async => null);
     final interceptor = OAuthInterceptor(mockOAuthChopper);
-    final expected = {};
+    final expected = <String, String>{};
 
     // act
     final result = await interceptor.onRequest(testRequest);