/*
 * Copyright (c) 杭州颉创科技有限公司 2025. All rights reserved.
 * This source file is licensed under the MIT License found in the
 * LICENSE file in the root directory of this source tree.
 */

package simcu::simapi.openapi

import std.reflect.*
import std.collection.*
import soulsoft_web_http.*
import soulsoft_web_routing.*
import soulsoft_extensions_options.*
import soulsoft_extensions_injection.*
import simcu::simapi.annotations.*
import simcu::simapi.openapi.models.*

/**
 * @brief 提供 OpenAPI 端点约定扩展。
 */
public interface OpenApiEndpointConventionBuilderExtensions {
    /**
     * @brief 为端点附加 OpenAPI 元数据。
     * @param metadata 要附加的 OpenAPI 元数据。
     * @return 当前端点约定构建器实例。
     */
    func withOpenApi(metadata: SimApiDoc): EndpointConventionBuilder
}

/**
 * @brief 提供 OpenAPI 文档路由映射扩展。
 */
public interface OpenApiEndpointRouteBuilderExtension {
    /**
     * @brief 映射指定模式的 OpenAPI 文档路由。
     * @param pattern OpenAPI 文档路由模式。
     * @return 当前端点路由构建器实例。
     */
    func mapOpenApi(pattern: String): EndpointRouteBuilder
}

/**
 * @brief 提供 OpenAPI 服务注册扩展。
 */
public interface OpenApiServiceCollectionExtensions {
    /**
     * @brief 注册默认文档名称的 OpenAPI 服务并配置选项。
     * @param configureOptions 用于配置 OpenAPI 选项的回调。
     * @return 当前服务集合实例。
     */
    func addOpenApi(configureOptions: (OpenApiOptions) -> Unit): ServiceCollection {
        addOpenApi("v1", configureOptions)
    }

    /**
     * @brief 注册指定文档名称的 OpenAPI 服务并配置选项。
     * @param documentName OpenAPI 文档名称。
     * @param configureOptions 用于配置 OpenAPI 选项的回调。
     * @return 当前服务集合实例。
     */
    func addOpenApi(documentName: String, configureOptions: (OpenApiOptions) -> Unit): ServiceCollection
}

/**
 * @brief 提供 OpenAPI UI 中间件扩展。
 */
public interface OpenApiUIMiddlewareExtensions {
    /**
     * @brief 启用 OpenAPI UI 中间件。
     */
    func useOpenApiUI(): Unit
}

/**
 * @brief 为动态注册的路由提供认证和响应类型元数据扩展。
 */
public interface SimApiEndpointMetadataExtensions {
    func withSimApiAuth(auth: SimApiAuth): EndpointConventionBuilder
    func withResponseType(typeInfo: TypeInfo): EndpointConventionBuilder
}

/**
 * @brief 定义 OpenAPI 文档提供器接口。
 */
public interface IDocumentProvider {
    /**
     * @brief 返回已注册的文档名称集合。
     * @return 当前可用的文档名称集合。
     */
    func getDooucmentNames(): Collection<String>
    /**
     * @brief 按名称创建 OpenAPI 文档。
     * @param documentName 要创建的文档名称。
     * @return 生成后的 OpenAPI 文档。
     */
    func create(documentName: String, services: IServiceProvider): OpenApiDocument
}
