add documentation

OpenIddict.Api.Models/src/Constants/OpenIddictApiConstants.cs

@@ -5,6 +5,23 @@ namespace SharpGrip.OpenIddict.Api.Models.Constants
 {
     public static class OpenIddictApiConstants
     {
+        public static class Api
+        {
+            public const string ApiRoutePrefix = "api/open-id";
+
+            public const string ApplicationApiRoute = "application";
+            public const string ApplicationApiAccessScope = "open_id_application_api_access";
+
+            public const string AuthorizationApiRoute = "authorization";
+            public const string AuthorizationApiAccessScope = "open_id_authorization_api_access";
+
+            public const string ScopeApiRoute = "scope";
+            public const string ScopeApiAccessScope = "open_id_scope_api_access";
+
+            public const string TokenApiRoute = "token";
+            public const string TokenApiAccessScope = "open_id_token_api_access";
+        }
+
         public static class Application
         {
             public static IDictionary<string, string> ClientTypes => new Dictionary<string, string>

OpenIddict.Api/src/Authorization/ApiAccessFilter.cs

@@ -17,9 +17,9 @@ public class ApiAccessFilter<TApplication, TAuthorization, TScope, TToken, TKey>
         where TToken : OpenIddictEntityFrameworkCoreToken<TKey, TApplication, TAuthorization>
         where TKey : struct, IEquatable<TKey>
     {
-        private readonly OpenIddictApiOptions openIddictApiOptions;
+        private readonly OpenIddictApiConfiguration openIddictApiOptions;
 
-        public ApiAccessFilter(IOptions<OpenIddictApiOptions> openIddictApiOptions)
+        public ApiAccessFilter(IOptions<OpenIddictApiConfiguration> openIddictApiOptions)
         {
             this.openIddictApiOptions = openIddictApiOptions.Value;
         }

OpenIddict.Api/src/Extensions/OpenIddictBuilderExtensions.cs

@@ -14,37 +14,58 @@ namespace SharpGrip.OpenIddict.Api.Extensions
 {
     public static class OpenIddictBuilderExtensions
     {
-        public static OpenIddictEntityFrameworkCoreBuilder AddApi<TKey>(this OpenIddictEntityFrameworkCoreBuilder openIddictEntityFrameworkCoreBuilder) where TKey : struct, IEquatable<TKey>
+        /// <summary>
+        /// Enables and exposes the OpenIddict API endpoints using the default OpenIddict Entity Framework Core entities.
+        /// </summary>
+        /// <param name="openIddictEntityFrameworkCoreBuilder">The services builder used by OpenIddict to register new services.</param>
+        /// <param name="openIddictApiConfiguration">The configuration delegate used to configure the OpenIddict API.</param>
+        /// <typeparam name="TKey"></typeparam>
+        /// <returns>The <see cref="OpenIddictEntityFrameworkCoreBuilder"/> instance.</returns>
+        public static OpenIddictEntityFrameworkCoreBuilder AddApi<TKey>(this OpenIddictEntityFrameworkCoreBuilder openIddictEntityFrameworkCoreBuilder,
+            Action<OpenIddictApiConfiguration>? openIddictApiConfiguration = null) where TKey : struct, IEquatable<TKey>
         {
-            return openIddictEntityFrameworkCoreBuilder
-                .AddApi<OpenIddictEntityFrameworkCoreApplication<TKey>, OpenIddictEntityFrameworkCoreAuthorization<TKey>, OpenIddictEntityFrameworkCoreScope<TKey>, OpenIddictEntityFrameworkCoreToken<TKey>, TKey>();
+            return openIddictEntityFrameworkCoreBuilder.AddApi<OpenIddictEntityFrameworkCoreApplication<TKey>,
+                OpenIddictEntityFrameworkCoreAuthorization<TKey>,
+                OpenIddictEntityFrameworkCoreScope<TKey>,
+                OpenIddictEntityFrameworkCoreToken<TKey>, TKey>(openIddictApiConfiguration);
         }
 
+        /// <summary>
+        /// Enables and exposes the OpenIddict API endpoints using custom OpenIddict entities, derived from the default OpenIddict Entity Framework Core entities.
+        /// </summary>
+        /// <param name="openIddictEntityFrameworkCoreBuilder">The services builder used by OpenIddict to register new services.</param>
+        /// <param name="openIddictApiConfiguration">The configuration delegate used to configure the OpenIddict API.</param>
+        /// <typeparam name="TApplication"></typeparam>
+        /// <typeparam name="TAuthorization"></typeparam>
+        /// <typeparam name="TScope"></typeparam>
+        /// <typeparam name="TToken"></typeparam>
+        /// <typeparam name="TKey"></typeparam>
+        /// <returns>The <see cref="OpenIddictEntityFrameworkCoreBuilder"/> instance.</returns>
         public static OpenIddictEntityFrameworkCoreBuilder AddApi<TApplication, TAuthorization, TScope, TToken, TKey>(this OpenIddictEntityFrameworkCoreBuilder openIddictEntityFrameworkCoreBuilder,
-            Action<OpenIddictApiOptions>? openIddictApiOptions = null)
+            Action<OpenIddictApiConfiguration>? openIddictApiConfiguration = null)
             where TApplication : OpenIddictEntityFrameworkCoreApplication<TKey, TAuthorization, TToken>
             where TAuthorization : OpenIddictEntityFrameworkCoreAuthorization<TKey, TApplication, TToken>
             where TScope : OpenIddictEntityFrameworkCoreScope<TKey>
             where TToken : OpenIddictEntityFrameworkCoreToken<TKey, TApplication, TAuthorization>
             where TKey : struct, IEquatable<TKey>
         {
-            var defaultOpenIddictApiOptions = new OpenIddictApiOptions();
+            var defaultOpenIddictApiConfiguration = new OpenIddictApiConfiguration();
 
-            if (openIddictApiOptions != null)
+            if (openIddictApiConfiguration != null)
             {
-                openIddictApiOptions.Invoke(defaultOpenIddictApiOptions);
-                openIddictEntityFrameworkCoreBuilder.Services.Configure(openIddictApiOptions);
+                openIddictApiConfiguration.Invoke(defaultOpenIddictApiConfiguration);
+                openIddictEntityFrameworkCoreBuilder.Services.Configure(openIddictApiConfiguration);
             }
 
             openIddictEntityFrameworkCoreBuilder.Services.AddSingleton<Mapper<TApplication, TAuthorization, TScope, TToken, TKey>, Mapper<TApplication, TAuthorization, TScope, TToken, TKey>>();
             openIddictEntityFrameworkCoreBuilder.Services.AddScoped<ModelValidator, ModelValidator>();
-            openIddictEntityFrameworkCoreBuilder.AddApiControllers<TApplication, TAuthorization, TScope, TToken, TKey>(defaultOpenIddictApiOptions);
+            openIddictEntityFrameworkCoreBuilder.AddApiControllers<TApplication, TAuthorization, TScope, TToken, TKey>(defaultOpenIddictApiConfiguration);
 
             return openIddictEntityFrameworkCoreBuilder;
         }
 
         private static void AddApiControllers<TApplication, TAuthorization, TScope, TToken, TKey>(this OpenIddictEntityFrameworkCoreBuilder openIddictEntityFrameworkCoreBuilder,
-            OpenIddictApiOptions openIddictApiOptions)
+            OpenIddictApiConfiguration openIddictApiOptions)
             where TApplication : OpenIddictEntityFrameworkCoreApplication<TKey, TAuthorization, TToken>
             where TAuthorization : OpenIddictEntityFrameworkCoreAuthorization<TKey, TApplication, TToken>
             where TScope : OpenIddictEntityFrameworkCoreScope<TKey>
@@ -55,6 +76,7 @@ private static void AddApiControllers<TApplication, TAuthorization, TScope, TTok
             {
                 applicationPartManager.FeatureProviders.Add(new ControllerFeatureProvider<TApplication, TAuthorization, TScope, TToken, TKey>());
             });
+
             openIddictEntityFrameworkCoreBuilder.Services.Configure<MvcOptions>(options =>
             {
                 options.Filters.Add<ApiAccessFilter<TApplication, TAuthorization, TScope, TToken, TKey>>();

OpenIddict.Api/src/Options/OpenIddictApiConfiguration.cs

@@ -0,0 +1,64 @@
+using SharpGrip.OpenIddict.Api.Models.Constants;
+
+namespace SharpGrip.OpenIddict.Api.Options
+{
+    /// <summary>
+    /// Exposes the configuration options to customize the OpenIddict API.
+    /// </summary>
+    public class OpenIddictApiConfiguration
+    {
+        /// <summary>
+        /// The API route prefix prefixes all API routes present. Defaults to the value of <see cref="OpenIddictApiConstants.Api.ApiRoutePrefix"/>.
+        /// </summary>
+        /// <see cref="OpenIddictApiConstants.Api"/>
+        public string ApiRoutePrefix { get; set; } = OpenIddictApiConstants.Api.ApiRoutePrefix;
+
+        /// <summary>
+        /// The base route for the <c>Application</c> endpoints. Defaults to the value of <see cref="OpenIddictApiConstants.Api.ApplicationApiRoute"/>.
+        /// </summary>
+        /// <see cref="OpenIddictApiConstants.Api"/>
+        public string ApplicationApiRoute { get; set; } = OpenIddictApiConstants.Api.ApplicationApiRoute;
+
+        /// <summary>
+        /// The access scope required to be present in the claims principal in order to access the <c>Application</c> endpoints. Default to <see cref="OpenIddictApiConstants.Api.ApplicationApiAccessScope"/>.
+        /// </summary>
+        /// <see cref="OpenIddictApiConstants.Api"/>
+        public string ApplicationApiAccessScope { get; set; } = OpenIddictApiConstants.Api.ApplicationApiAccessScope;
+
+        /// <summary>
+        /// The base route for the <c>Authorization</c> endpoints. Defaults to the value of <see cref="OpenIddictApiConstants.Api.AuthorizationApiRoute"/>.
+        /// </summary>
+        /// <see cref="OpenIddictApiConstants.Api"/>
+        public string AuthorizationApiRoute { get; set; } = OpenIddictApiConstants.Api.AuthorizationApiRoute;
+
+        /// <summary>
+        /// The access scope required to be present in the claims principal in order to access the <c>Authorization</c> endpoints. Default to <see cref="OpenIddictApiConstants.Api.AuthorizationApiAccessScope"/>.
+        /// </summary>
+        /// <see cref="OpenIddictApiConstants.Api"/>
+        public string AuthorizationApiAccessScope { get; set; } = OpenIddictApiConstants.Api.AuthorizationApiAccessScope;
+
+        /// <summary>
+        /// The base route for the <c>Scope</c> endpoints. Defaults to the value of <see cref="OpenIddictApiConstants.Api.ScopeApiRoute"/>.
+        /// </summary>
+        /// <see cref="OpenIddictApiConstants.Api"/>
+        public string ScopeApiRoute { get; set; } = OpenIddictApiConstants.Api.ScopeApiRoute;
+
+        /// <summary>
+        /// The access scope required to be present in the claims principal in order to access the <c>Scope</c> endpoints. Default to <see cref="OpenIddictApiConstants.Api.ScopeApiAccessScope"/>. 
+        /// </summary>
+        /// <see cref="OpenIddictApiConstants.Api"/>
+        public string ScopeApiAccessScope { get; set; } = OpenIddictApiConstants.Api.ScopeApiAccessScope;
+
+        /// <summary>
+        /// The base route for the <c>Token</c> endpoints. Defaults to the value of <see cref="OpenIddictApiConstants.Api.TokenApiRoute"/>.
+        /// </summary>
+        /// <see cref="OpenIddictApiConstants.Api"/>
+        public string TokenApiRoute { get; set; } = OpenIddictApiConstants.Api.TokenApiRoute;
+
+        /// <summary>
+        /// The access scope required to be present in the claims principal in order to access the <c>Token</c> endpoints. Default to <see cref="OpenIddictApiConstants.Api.TokenApiAccessScope"/>. 
+        /// </summary>
+        /// <see cref="OpenIddictApiConstants.Api"/>
+        public string TokenApiAccessScope { get; set; } = OpenIddictApiConstants.Api.TokenApiAccessScope;
+    }
+}

OpenIddict.Api/src/Routing/RoutePrefixConvention.cs

@@ -12,7 +12,7 @@ public class RoutePrefixConvention : IApplicationModelConvention
         private readonly AttributeRouteModel attributeRoutePrefixModel;
         private readonly IDictionary<string, Type> controllerTypeData;
 
-        public RoutePrefixConvention(OpenIddictApiOptions openIddictApiOptions, IDictionary<string, Type> controllerTypeData)
+        public RoutePrefixConvention(OpenIddictApiConfiguration openIddictApiOptions, IDictionary<string, Type> controllerTypeData)
         {
             this.controllerTypeData = controllerTypeData;
             attributeRoutePrefixModel = new AttributeRouteModel(new RouteAttribute(openIddictApiOptions.ApiRoutePrefix));