update sample project, compiler config options descriptions and invalid deps

vnikolova · vnikolova · commit c3130ed77df8 · 2026-01-13T13:46:53.000+01:00
diff --git a/codeSnippets/snippets/openapi-spec-gen/README.md b/codeSnippets/snippets/openapi-spec-gen/README.md
@@ -5,14 +5,6 @@ extension of the Ktor Gradle plugin.
 
 > This sample is a part of the [`codeSnippets`](../../README.md) Gradle project.
 
-## Generate the OpenAPI specification
-
-```bash
-./gradlew :openapi-spec-gen:buildOpenApi
-```
-
-The generated OpenAPI specification is located in `build/ktor/openapi/generated.json`.
-
 ## Run the application
 
 To run the application, execute the following command in the repository's root directory:
@@ -21,4 +13,8 @@ To run the application, execute the following command in the repository's root d
 ./gradlew :openapi-spec-gen:run
 ```
 
-Navigate to [http://0.0.0.0:8080/docs](http://0.0.0.0:8080/docs) to access the OpenAPI documentation.
+To view the OpenAPI documentation, navigate to the following URLs:
+
+- [http://0.0.0.0:8080/docs.json](http://0.0.0.0:8080/docs.json)
+- [http://0.0.0.0:8080/openApi](http://0.0.0.0:8080/openApi) to view the OpenAPI UI for the API spec.
+- [http://0.0.0.0:8080/swaggerUI](http://0.0.0.0:8080/swaggerUI) to view the Swagger UI for the API spec.
diff --git a/codeSnippets/snippets/openapi-spec-gen/build.gradle.kts b/codeSnippets/snippets/openapi-spec-gen/build.gradle.kts
@@ -1,4 +1,4 @@
-val ktor_version = "3.4.0-eap-1505" //TODO: replace with project version
+val ktor_version = "3.4.0-eap-1511"
 val kotlin_version: String by project
 val logback_version: String by project
 
@@ -14,27 +14,25 @@ application {
 
 repositories {
     mavenCentral()
-    maven { url = uri("https://maven.pkg.jetbrains.space/public/p/ktor/eap") }
+    maven("https://oss.sonatype.org/content/repositories/snapshots")
 }
 
 ktor {
-    @OptIn(io.ktor.plugin.OpenApiPreview::class)
     openApi {
-        title = "OpenAPI example"
-        version = "2.1"
-        summary = "This is a sample API"
+        enabled = true
+        codeInferenceEnabled = true
+        onlyCommented = false
     }
 }
 
-// Builds OpenAPI specification automatically
-tasks.processResources {
-    dependsOn("buildOpenApi")
-}
 
 dependencies {
     implementation("io.ktor:ktor-server-core:$ktor_version")
-    implementation("io.ktor:ktor-server-routing-annotate:${ktor_version}")
-    implementation("io.ktor:ktor-server-openapi:${ktor_version}")
+    implementation("io.ktor:ktor-server-routing-annotate:$ktor_version")
+    implementation("io.ktor:ktor-server-openapi:$ktor_version")
+    implementation("io.ktor:ktor-server-content-negotiation:${ktor_version}")
+    implementation("io.ktor:ktor-serialization-kotlinx-json:${ktor_version}")
+    implementation("io.ktor:ktor-server-swagger:${ktor_version}")
     implementation("io.ktor:ktor-server-netty:$ktor_version")
     implementation("ch.qos.logback:logback-classic:$logback_version")
     testImplementation("io.ktor:ktor-server-test-host-jvm:$ktor_version")
diff --git a/codeSnippets/snippets/openapi-spec-gen/src/main/kotlin/com/example/Application.kt b/codeSnippets/snippets/openapi-spec-gen/src/main/kotlin/com/example/Application.kt
@@ -1,18 +1,82 @@
 package com.example
 
+import io.ktor.annotate.OpenApiDocSource
 import io.ktor.annotate.annotate
+import io.ktor.annotate.generateOpenApiDoc
 import io.ktor.http.*
+import io.ktor.openapi.OpenApiDoc
+import io.ktor.openapi.OpenApiInfo
 import io.ktor.openapi.jsonSchema
+import io.ktor.serialization.kotlinx.json.json
 import io.ktor.server.application.*
+import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
 import io.ktor.server.plugins.openapi.*
+import io.ktor.server.plugins.swagger.swaggerUI
 import io.ktor.server.request.*
 import io.ktor.server.response.*
 import io.ktor.server.routing.*
 import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
 
 fun main(args: Array<String>): Unit = io.ktor.server.netty.EngineMain.main(args)
 
 fun Application.module() {
+    install(ContentNegotiation) {
+        json()
+        json(Json {
+            encodeDefaults = false
+        })
+    }
+    routing {
+        // Main page for marketing
+        get("/") {
+            call.respondText("<html><body><h1>Hello, World</h1></body></html>", ContentType.Text.Html)
+        }
+
+        /**
+         * API endpoints for users.
+         *
+         * These will appear in the resulting OpenAPI document.
+         */
+        val apiRoute = userCrud()
+
+        get("/docs.json") {
+            val docs = generateOpenApiDoc(
+                OpenApiDoc(info = OpenApiInfo("My API", "1.0")),
+                apiRoute.descendants()
+            )
+            call.respond(docs)
+        }
+
+        /**
+         * View the generated UI for the API spec.
+         */
+        openAPI("/openApi"){
+            outputPath = "docs/routes"
+            // title, version, etc.
+            info = OpenApiInfo("My API from routes", "1.0.0")
+            // which routes to read from to build the model
+            // by default, it will check for `openapi/documentation.yaml` then use the routing root as a fallback
+            source = OpenApiDocSource.RoutingSource(ContentType.Application.Json) {
+                apiRoute.descendants()
+            }
+        }
+
+        /**
+         * View the Swagger flavor of the UI for the API spec.
+         */
+        swaggerUI("/swaggerUI") {
+            info = OpenApiInfo("My API", "1.0")
+            source = OpenApiDocSource.RoutingSource(ContentType.Application.Json) {
+                apiRoute.descendants()
+            }
+        }
+    }
+}
+
+private fun Unit.descendants(): Sequence<Route> {}
+
+fun Application.userCrud() {
     routing {
         /**
          * Hello, world.
@@ -119,6 +183,5 @@ fun Application.module() {
         )
     }
 }
-
 @Serializable
 data class User(val id: ULong, val name: String)
diff --git a/codeSnippets/snippets/tutorial-server-db-integration/gradle/libs.versions.toml b/codeSnippets/snippets/tutorial-server-db-integration/gradle/libs.versions.toml
@@ -23,7 +23,7 @@ logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "lo
 ktor-server-config-yaml = { module = "io.ktor:ktor-server-config-yaml-jvm", version.ref = "ktor-version" }
 ktor-server-test-host = { module = "io.ktor:ktor-server-test-host-jvm", version.ref = "ktor-version" }
 kotlin-test-junit = { module = "org.jetbrains.kotlin:kotlin-test-junit", version.ref = "kotlin-version" }
-ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation-jvm", version.ref = "ktor-version" }
+ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor-version" }
 
 [plugins]
 kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin-version" }
diff --git a/codeSnippets/snippets/tutorial-server-docker-compose/build.gradle.kts b/codeSnippets/snippets/tutorial-server-docker-compose/build.gradle.kts
@@ -39,6 +39,6 @@ dependencies {
     implementation("ch.qos.logback:logback-classic:$logback_version")
     implementation("io.ktor:ktor-server-config-yaml:$ktor_version")
     testImplementation("io.ktor:ktor-server-test-host-jvm")
-    testImplementation("io.ktor:ktor-client-content-negotiation-jvm:$ktor_version")
+    testImplementation("io.ktor:ktor-client-content-negotiation:$ktor_version")
     testImplementation("org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version")
 }
diff --git a/codeSnippets/snippets/tutorial-server-websockets/build.gradle.kts b/codeSnippets/snippets/tutorial-server-websockets/build.gradle.kts
@@ -32,5 +32,5 @@ dependencies {
     implementation("ch.qos.logback:logback-classic:$logback_version")
     testImplementation("io.ktor:ktor-server-test-host-jvm")
     testImplementation("org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version")
-    testImplementation("io.ktor:ktor-client-content-negotiation-jvm:$ktor_version")
+    testImplementation("io.ktor:ktor-client-content-negotiation:$ktor_version")
 }
diff --git a/topics/openapi-spec-generation.md b/topics/openapi-spec-generation.md
@@ -76,17 +76,19 @@ ktor {
 <deflist>
 <def>
 <title><code>enabled</code></title>
-Enables or disables OpenAPI metadata generation during compilation.
+Enables or disables OpenAPI route annotation code generation. Defaults to <code>false</code>.
 </def>
 <def>
 <title><code>codeInferenceEnabled</code></title>
-Controls whether the compiler attempts to infer OpenAPI metadata from routing code. Disable this option if inference
-produces incorrect results or if you prefer to define metadata explicitly using annotations.
-For more details, see <a href="#code-inference">Code inference rules</a>.
+Controls whether the compiler attempts to infer OpenAPI metadata from routing code. Defaults to <code>true</code>. 
+Disable this option if inference produces incorrect results or if you prefer to define metadata explicitly using
+annotations.
+For more details, see <a href="#code-inference">the code inference rules</a>.
 </def>
 <def>
 <title><code>onlyCommented</code></title>
-Limits metadata generation to routes that contain comment annotations. By default, all routes are processed.
+Limits metadata generation to routes that contain comment annotations. Defaults to <code>false</code>, meaning all
+routing calls are processed except those explicitly marked with <code>@ignore</code>.
 </def>
 </deflist>
 
@@ -95,7 +97,7 @@ Limits metadata generation to routes that contain comment annotations. By defaul
 The Ktor compiler plugin analyzes your server routing DSL to determine the structural shape of your API. This analysis
 is based solely on route declarations and does not inspect the contents of route handlers.
 
-From routing declarations, the compiler determines:
+The following is automatically inferred from the selectors in the routing API tree:
 - Merged paths (for example, `/api/v1/users/{id}`).
 - HTTP methods (such as `GET` and `POST`).
 - Path parameters.

Original file line number	Diff line number	Diff line change
`@@ -39,6 +39,6 @@ dependencies {`
`39`	`39`	`implementation("ch.qos.logback:logback-classic:$logback_version")`
`40`	`40`	`implementation("io.ktor:ktor-server-config-yaml:$ktor_version")`
`41`	`41`	`testImplementation("io.ktor:ktor-server-test-host-jvm")`
`42`		`- testImplementation("io.ktor:ktor-client-content-negotiation-jvm:$ktor_version")`
	`42`	`+ testImplementation("io.ktor:ktor-client-content-negotiation:$ktor_version")`
`43`	`43`	`testImplementation("org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version")`
`44`	`44`	`}`
Original file line number	Diff line number	Diff line change
`@@ -32,5 +32,5 @@ dependencies {`
`32`	`32`	`implementation("ch.qos.logback:logback-classic:$logback_version")`
`33`	`33`	`testImplementation("io.ktor:ktor-server-test-host-jvm")`
`34`	`34`	`testImplementation("org.jetbrains.kotlin:kotlin-test-junit:$kotlin_version")`
`35`		`- testImplementation("io.ktor:ktor-client-content-negotiation-jvm:$ktor_version")`
	`35`	`+ testImplementation("io.ktor:ktor-client-content-negotiation:$ktor_version")`
`36`	`36`	`}`