EonaCat.DoxaApi/DoxaApi/Generation/DoxaApiOptions.cs

using EonaCat.DoxaApi.Models;

namespace EonaCat.DoxaApi.Generation
{
    // This file is part of the EonaCat project(s) which is released under the Apache License.
    // See the LICENSE file or go to https://EonaCat.com/license for full license details.

    public sealed class DoxaApiOptions
    {
        public string Title { get; set; } = "DoxaApi Documentation";
        public string? Description { get; set; }
        public string Version { get; set; } = "v1";
        public string RoutePrefix { get; set; } = "doxa";
        public List<string> Servers { get; set; } = new();
        public string Theme { get; set; } = "auto";
        public string AccentColor { get; set; } = "#6366f1";

        /// <summary>
        /// Security schemes available to this API, keyed by scheme id. Populate via
        /// <see cref="AddApiKeyAuth"/>, <see cref="AddBearerAuth"/>, <see cref="AddBasicAuth"/>,
        /// or <see cref="AddOAuth2ClientCredentials"/>, or add custom entries directly.
        /// </summary>
        public Dictionary<string, SecuritySchemeModel> SecuritySchemes { get; } = new();

        /// <summary>
        /// If set, endpoints without an explicit [DoxaApiAuth]/[Authorize]/[DoxaApiAllowAnonymous]
        /// marker are assumed to require this scheme. Leave null to assume anonymous by default.
        /// </summary>
        public string? DefaultSecurityScheme { get; set; }

        /// <summary>
        /// When true, exposes a mock-response endpoint (/{prefix}/mock/...) that returns
        /// schema-shaped fake JSON for any documented operation without touching real
        /// controller code - useful for frontend teams working ahead of a backend.
        /// </summary>
        public bool EnableMockServer { get; set; } = true;

        /// <summary>
        /// When true, exposes a /{prefix}/console endpoint for running ad-hoc HTTP requests
        /// (method/url/headers/body) against the API, independent of any documented operation.
        /// </summary>
        public bool EnableConsole { get; set; } = true;

        public DoxaApiOptions AddApiKeyAuth(string id, string headerOrQueryName, string @in = "header", string? description = null)
        {
            SecuritySchemes[id] = new SecuritySchemeModel
            {
                Id = id,
                Type = "apiKey",
                In = @in,
                Name = headerOrQueryName,
                Description = description
            };
            return this;
        }

        public DoxaApiOptions AddBearerAuth(string id = "bearer", string bearerFormat = "JWT", string? description = null)
        {
            SecuritySchemes[id] = new SecuritySchemeModel
            {
                Id = id,
                Type = "http",
                Scheme = "bearer",
                BearerFormat = bearerFormat,
                Description = description ?? "Bearer token authentication"
            };
            return this;
        }

        public DoxaApiOptions AddBasicAuth(string id = "basic", string? description = null)
        {
            SecuritySchemes[id] = new SecuritySchemeModel
            {
                Id = id,
                Type = "http",
                Scheme = "basic",
                Description = description ?? "HTTP Basic authentication"
            };
            return this;
        }

        public DoxaApiOptions AddOAuth2ClientCredentials(string id, string tokenUrl, Dictionary<string, string>? scopes = null, string? description = null)
        {
            SecuritySchemes[id] = new SecuritySchemeModel
            {
                Id = id,
                Type = "oauth2",
                Description = description ?? "OAuth 2.0 client credentials flow",
                Flows = new OAuthFlowsModel
                {
                    ClientCredentials = new OAuthFlowModel
                    {
                        TokenUrl = tokenUrl,
                        Scopes = scopes ?? new Dictionary<string, string>()
                    }
                }
            };
            return this;
        }

        public DoxaApiOptions AddOAuth2AuthorizationCode(string id, string authorizationUrl, string tokenUrl, Dictionary<string, string>? scopes = null, string? description = null)
        {
            SecuritySchemes[id] = new SecuritySchemeModel
            {
                Id = id,
                Type = "oauth2",
                Description = description ?? "OAuth 2.0 authorization code flow",
                Flows = new OAuthFlowsModel
                {
                    AuthorizationCode = new OAuthFlowModel
                    {
                        AuthorizationUrl = authorizationUrl,
                        TokenUrl = tokenUrl,
                        Scopes = scopes ?? new Dictionary<string, string>()
                    }
                }
            };
            return this;
        }
    }
}