complete first draft of new basic openapi documentation

Author: SMILEY4

docs/openapi/advanced_topics/documenting_sse_routes.md

@@ -0,0 +1,30 @@
+# Documenting SSE Routes
+
+Server-Sent Events (SSE) routes can be documented for discoverability in the OpenAPI specification. While SSE functionality works normally in Ktor, documentation is achieved by wrapping SSE routes in a documented parent route.
+
+??? warning "Limited OpenAPI Support"
+
+**Important:** OpenAPI has limited support for Server-Sent Events. The specification does not officially define SSE endpoints, so not all documentation features work as expected or may not render correctly in documentation UIs.
+
+SSE documentation is primarily for discoverability and basic information. Advanced SSE features (event types, reconnection behavior, stream format) are not well-represented in OpenAPI.
+
+
+## Describing SSE-Routes
+
+SSE routes are documented by wrapping them in a parent route with documentation:
+
+```kotlin
+import io.ktor.server.sse.sse
+
+route({
+    description = "Server-sent events stream for real-time updates"
+    tags = listOf("events", "sse")
+}) {
+    sse("/events") {
+        // SSE implementation
+        send(ServerSentEvent(data = "Hello"))
+    }
+}
+```
+
+All standard route documentation options are (theoretically) available. See [Basic Route Documentation]() for complete documentation options.

docs/openapi/advanced_topics/documenting_webhooks.md

@@ -0,0 +1,36 @@
+# Documenting Webhooks
+
+Webhooks are HTTP callbacks that your API sends to external systems. While webhooks are not part of your server's request handling, they can be documented in the OpenAPI specification to help API consumers understand what data your API will send to their endpoints.
+
+??? warning "Documentation Only"
+
+**Important:** Webhook documentation is purely informational. It does not create callable Ktor routes and has no impact on your application's routing or request handling.
+
+Webhooks appear only in the generated OpenAPI specification under the `webhooks` section. They document HTTP requests your API makes to external systems, not requests it receives.
+
+## Describing Webhooks
+
+Webhooks are documented using the webhook function:
+
+```kotlin
+routing {
+    route("webhooks") {
+        webhook(HttpMethod.Post, "concertAlert") {
+            description = "Notify the registered URL with details of an upcoming concert"
+            request {
+                body<String> {
+                    mediaTypes(ContentType.Text.Plain)
+                    required = true
+                }
+            }
+        }
+    }
+}
+```
+
+Parameters:
+
+- httpMethod: HTTP method for the webhook (typically HttpMethod.Post)
+- eventName: Unique identifier for the webhook event (e.g., "newOrder", "userCreated")
+
+All standard route documentation options are available. See [Basic Route Documentation]() for complete documentation options.

docs/openapi/advanced_topics/multiple_openapi_specifications.md

@@ -0,0 +1,121 @@
+# Multiple API Specifications
+
+The OpenAPI plugin supports generating multiple independent specifications from a single application. This enables API versioning, separation of internal and external APIs, or organizing endpoints by product or team.
+
+Each specification has a unique identifier, its own configuration, and contains only the routes assigned to it. Specifications are generated and served independently.
+
+## Configuring Specifications
+
+Each specification can have its own configuration that extends or overrides the base plugin configuration.
+
+All configuration options available in the base plugin config are available for individual specifications:
+
+```kotlin
+install(OpenApi) {
+    // Base configuration for all specifications
+    info {
+        title = "My API"
+    }
+    
+    // Define specification "v1"
+    spec("v1") {
+        info {
+            version = "1.0.0"
+        }
+    }
+    
+    // Define specification "v2"
+    spec("v2") {
+        info {
+            version = "2.0.0"
+        }
+    }
+}
+```
+
+Each specification is identified by a unique string (e.g., "v1", "v2", "internal").
+
+## Assigning Routes to Specifications
+
+Routes must be assigned to specifications to appear in them. Assignment can be done explicitly in route documentation or automatically via an assigner function.
+
+### Assignment at Route Documentation
+
+The `specName` property assigns a route to a specific specification:
+
+```kotlin
+get("users", {
+    specName = "v1"
+    description = "Get users (v1)"
+}) { }
+```
+
+Routes can be easily assigned in groups by adding the `specName` at a parent route:
+
+```kotlin
+route("v1", {
+    specName = "v1" // All child routes assigned to v1
+}) {
+    get("users") { }
+    get("products") { }
+    get("orders") { }
+}
+```
+
+All routes within this block are automatically assigned to the "v1" specification through inheritance.
+
+### Assignment via Assigner Function
+
+Routes can be automatically assigned based on their properties using an assigner function:
+
+```kotlin
+install(OpenApi) {
+    specAssigner = { url, tags ->
+        when (url.firstOrNull()) {
+            "v1" -> "v1"
+            "v2" -> "v2"
+            "internal" -> "internal"
+            else -> OpenApiPluginConfig.DEFAULT_SPEC_ID
+        }
+    }
+}
+```
+
+The function receives:
+
+- `url`: URL path as a list of segments (e.g., `["api", "v1", "users"]` for `/api/v1/users`)
+- `tags`: Tags assigned to the route
+
+The function returns the specification identifier to assign the route to.
+
+### Unassigned Routes
+
+Routes without an assignment are assigned to the default specification with the identifier `OpenApiPluginConfig.DEFAULT_SPEC_ID`. The default specification only exists if any routes are assigned to it.
+
+## Serving Multiple Specifications
+
+Each specification is served independently via HTTP routes.
+
+```kotlin
+routing {
+    // v1 specification
+    route("v1/api.json") {
+        openApi("v1")
+    }
+    
+    // v2 specification
+    route("v2/api.json") {
+        openApi("v2")
+    }
+    
+    // Internal specification
+    route("internal/api.json") {
+        openApi("internal")
+    }
+}
+```
+
+More information on how to handle multiple specifications in UIs:
+
+- with [Swagger UI]()
+- with [ReDoc]()

docs/openapi/advanced_topics/typesafe_routing_support.md

@@ -0,0 +1,100 @@
+# Type-Safe Routing Support
+
+The OpenAPI plugin supports Ktor's type-safe routing via the Resources plugin. Resource classes can be used to define routes, and the plugin can automatically extract parameter information from resource class properties.
+
+## Setup
+
+Type-safe routing support requires additional configuration:
+
+### Installed Resources Plugin
+
+The Ktor Resources plugin must be installed separately:
+
+```kotlin
+dependencies {
+    implementation("io.ktor:ktor-server-resources:$ktor_version")
+}
+```
+
+```kotlin
+install(Resources)
+install(OpenApi)
+```
+
+### Configure Schema Generator
+
+Type-safe routing requires the kotlinx.serialization schema generator:
+
+```kotlin
+install(OpenApi) {
+    schemas {
+        generator = SchemaGenerator.kotlinx()
+    }
+}
+```
+
+### Enable Auto-Documentation (Optional)
+
+The `autoDocumentResourcesRoutes` option automatically extracts parameter information from resource classes:
+
+```kotlin
+install(OpenApi) {
+    autoDocumentResourcesRoutes = true
+}
+```
+
+When enabled, the plugin automatically documents:
+
+- Path parameters from resource class properties
+- Query parameters from resource class properties
+- Parameter types, nullability, and default values
+
+This reduces the need for manual parameter documentation in resource routes.
+
+## Documenting Resource Routes
+
+### Import Documented Resource Functions
+
+Use documented resource route functions from `io.github.smiley4.ktoropenapi.resources`:
+
+```kotlin
+import io.github.smiley4.ktoropenapi.resources.get
+import io.github.smiley4.ktoropenapi.resources.post
+import io.github.smiley4.ktoropenapi.resources.put
+import io.github.smiley4.ktoropenapi.resources.delete
+```
+
+### Document Resource Routes
+
+The documentation block works the same as with standard routes:
+
+```kotlin
+import io.github.smiley4.ktoropenapi.resources.get
+
+@Serializable
+@Resource("users")
+class Users
+
+@Serializable
+@Resource("{id}")
+class User(val parent: Users, val id: String)
+
+
+get<User>({
+    description = "Retrieve a user by ID"
+    tags = listOf("users")
+    
+    response {
+        code(HttpStatusCode.OK) {
+            description = "User found"
+            body<UserResponse>()
+        }
+        code(HttpStatusCode.NotFound) {
+            description = "User not found"
+        }
+    }
+}) {
+    val user = call.parameters["id"]
+    // Handler implementation
+}
+```

docs/openapi/core_concepts/how_it_works.md

@@ -48,7 +48,7 @@ httpMethod("path", {
 
 Type information from the documentation DSL is automatically converted to OpenAPI schemas. Schemas can be defined locally (
 inline with usage) or globally (in the plugin configuration).
-The plugin uses [schema-kenerator](https://github.com/SMILEY4/schema-kenerator) to generate its schemas from kotlin classes and supports
+The plugin uses [schema-kenerator](https://github.com/SMILEY4/schema-kenerator) to generate its schemas from kotlin classes and supports.
 multiple schema generation strategies:
 
 - Reflection-based (default): Analyzes Kotlin types using reflection