// build.gradle.kts
plugins {
    id("io.github.tabilzad.inspektor") version "0.11.3-alpha"
}

@GenerateOpenApi
fun Application.module() {
    routing {
        get("/hello") {
            call.respondText("Hello, World!")
        }

        post("/users") {
            val user = call.receive<CreateUserRequest>()
            call.respond(HttpStatusCode.Created, user)
        }
    }
}

data class CreateUserRequest(val name: String, val email: String)

swagger {
    documentation {
        info {
            title = "My API"
            description = "API documentation for my Ktor server"
            version = "1.0.0"
            contact {
                name = "API Support"
                url = "https://example.com/support"
            }
        }
        servers = listOf("https://api.example.com", "http://localhost:8080")
    }

    pluginOptions {
        format = "yaml"  // or "json"
    }
}

@GenerateOpenApi
fun Route.usersApi() {
    route("/api/v1/users") {
        get { /* List users */ }
        post { /* Create user */ }

        route("/{id}") {
            get { /* Get user by ID */ }
            put { /* Update user */ }
            delete { /* Delete user */ }
        }
    }
}

@GenerateOpenApi
fun Application.apiModule() {
    routing {
        usersApi()      // All routes are included
        productsApi()   // Even nested route functions
        ordersApi()
    }
}

@GenerateOpenApi
fun Route.ordersApi() {
    route("/orders") {
        @KtorDescription(
            summary = "Create Order",
            description = "Creates a new order with the provided items"
        )
        post {
            val order = call.receive<CreateOrderRequest>()
            // ...
        }
    }
}

@KtorSchema("Request payload for creating a new order")
data class CreateOrderRequest(
    @KtorField("List of items to include in the order")
    val items: List<OrderItem>,

    @KtorField("Optional discount code")
    val discountCode: String? = null
)

/**
 * Request payload for creating a new order
 * @property items List of items to include in the order
 * @property discountCode Optional discount code
 */
data class CreateOrderRequest(
    val items: List<OrderItem>,
    val discountCode: String? = null
)

object ApiHeaders {
    /** Identifies the tenant the request is scoped to. */
    const val TENANT_ID = "X-Tenant-Id"
}

get("/orders") {
    /** The API key issued to the client. */
    val apiKey = call.request.headers["X-Api-Key"]

    val tenant = call.request.header(ApiHeaders.TENANT_ID) // description from the constant's KDoc

    /** Zero-based page index. */
    val page = call.request.queryParameters["page"]
}

@KtorHeaders([HeaderParam("X-Admin-Token", "Admin access token", required = true)])
route("/admin") {
    get("/users") { /* X-Admin-Token is documented here */ }
}

swagger {
    documentation {
        commonHeaders {
            header("X-Request-Id", description = "Correlation id propagated across services")
            header("X-Tenant-Id", description = "Tenant the request is scoped to", required = true)
        }
    }
}

post("/orders") {
    responds<Order>(HttpStatusCode.Created, description = "Order created successfully")
    responds<ErrorResponse>(HttpStatusCode.BadRequest, description = "Invalid request")
    respondsNothing(HttpStatusCode.Unauthorized)

    // Your handler code...
}

@KtorResponds(
    [
        ResponseEntry("201", Order::class, description = "Order created"),
        ResponseEntry("400", ErrorResponse::class, description = "Invalid request"),
        ResponseEntry("401", Nothing::class)
    ]
)
post("/orders") { /* ... */ }

@Tag(["Users"])
fun Route.usersApi() {
    get("/users") { /* tagged as "Users" */ }
    post("/users") { /* tagged as "Users" */ }
}

// Or on individual endpoints:
@GenerateOpenApi
fun Route.api() {
    @Tag(["Users"])
    get("/users") { /* ... */ }

    @Tag(["Products"])
    get("/products") { /* ... */ }
}

swagger {
    documentation {
        security {
            schemes {
                "bearerAuth" to SecurityScheme(
                    type = "http",
                    scheme = "bearer",
                    bearerFormat = "JWT"
                )
                "apiKey" to SecurityScheme(
                    type = "apiKey",
                    `in` = "header",
                    name = "X-API-Key"
                )
            }
            scopes {
                or { +"bearerAuth" }
                or { +"apiKey" }
            }
        }
    }
}

swagger {
    documentation {
        serialOverrides {
            typeOverride("java.time.Instant") {
                serializedAs = "string"
                format = "date-time"
                description = "ISO 8601 timestamp"
            }
            typeOverride("java.util.UUID") {
                serializedAs = "string"
                format = "uuid"
            }
        }
    }
}

@JsonClassDiscriminator("type")
sealed class PaymentMethod {
    data class CreditCard(val cardNumber: String, val cvv: String) : PaymentMethod()
    data class BankTransfer(val iban: String) : PaymentMethod()
}

swagger {
    documentation {
        polymorphicDiscriminator = "type"  // default
    }
}

swagger {
    pluginOptions {
        regenerationMode = "strict"  // default
    }
}