GH-49 Rework internal implementation and support dynamic API & KSP

build.gradle.kts

@@ -17,7 +17,7 @@ allprojects {
     apply(plugin = "maven-publish")
 
     group = "io.javalin.community.openapi"
-    version = "7.2.2"
+    version = "7.3.0-RC.1"
 
     repositories {
         mavenCentral()

docs/.vitepress/config.mjs

@@ -56,7 +56,8 @@ export default defineConfig({
         text: 'Advanced',
         collapsed: false,
         items: [
-          { text: 'Compile-time Configuration', link: '/advanced/configuration' },
+          { text: 'Static Configuration', link: '/advanced/configuration' },
+          { text: 'Scripting Configuration', link: '/advanced/scripting' },
           { text: 'Runtime Builder DSL', link: '/advanced/runtime-builder' },
         ],
       },

docs/advanced/configuration.md

@@ -1,75 +1,14 @@
-# Compile-time Configuration
+# Static Configuration
 
-Configure the annotation processor using a Groovy script. This allows custom type mappings, property filters, and advanced type processors.
+Pass key-value options to the backend at build time. The `info.*` options apply to both the annotation processor (APT/Kapt) and KSP; `openapi.groovy.path` is APT/Kapt-only.
 
-## Setup
+## Options
 
-Create a Groovy configuration script (e.g. `openapi.groovy`) anywhere in your project
-and point the annotation processor to it using the `openapi.groovy.path` option:
-
-```groovy
-import io.javalin.openapi.experimental.*
-
-@ExperimentalCompileOpenApiConfiguration
-class OpenApiConfiguration
-    implements OpenApiAnnotationProcessorConfigurer {
-
-    @Override
-    void configure(
-        OpenApiAnnotationProcessorConfiguration configuration
-    ) {
-        // Configuration goes here
-    }
-}
-```
-
-::: code-group
-
-```kotlin [Gradle (Kotlin)]
-kapt {
-    arguments {
-        arg(
-            "openapi.groovy.path",
-            "$projectDir/src/main/compile/openapi.groovy"
-        )
-    }
-}
-```
-
-```groovy [Gradle (Groovy)]
-kapt {
-    arguments {
-        arg(
-            'openapi.groovy.path',
-            "$projectDir/src/main/compile/openapi.groovy"
-        )
-    }
-}
-```
-
-```xml [Maven]
-<plugin>
-    <groupId>org.apache.maven.plugins</groupId>
-    <artifactId>maven-compiler-plugin</artifactId>
-    <configuration>
-        <compilerArgs>
-            <arg>-Aopenapi.groovy.path=${project.basedir}/src/main/compile/openapi.groovy</arg>
-        </compilerArgs>
-    </configuration>
-</plugin>
-```
-
-:::
-
-## Annotation Processor Options
-
-The following options can be passed to the annotation processor:
-
-| Option                  | Description                                              |
-|-------------------------|----------------------------------------------------------|
-| `openapi.info.title`    | Set the `info.title` field in the generated specification |
-| `openapi.info.version`  | Set the `info.version` field in the generated specification |
-| `openapi.groovy.path`   | Path to the Groovy configuration script                   |
+| Option                 | Description                                                                                          |
+|------------------------|------------------------------------------------------------------------------------------------------|
+| `openapi.info.title`   | Set the `info.title` field in the generated specification                                            |
+| `openapi.info.version` | Set the `info.version` field in the generated specification                                          |
+| `openapi.groovy.path`  | Path to a Groovy script for advanced configuration (APT/Kapt only, see [Scripting Configuration](./scripting)) |
 
 ::: code-group
 
@@ -82,6 +21,13 @@ kapt {
 }
 ```
 
+```kotlin [Gradle (KSP)]
+ksp {
+    arg("openapi.info.title", "My API")
+    arg("openapi.info.version", "1.0.0")
+}
+```
+
 ```xml [Maven]
 <plugin>
     <groupId>org.apache.maven.plugins</groupId>
@@ -97,108 +43,4 @@ kapt {
 
 :::
 
-## Custom Type Mappings
-
-Map custom types to simple OpenAPI types:
-
-```groovy
-void configure(
-    OpenApiAnnotationProcessorConfiguration configuration
-) {
-    configuration.simpleTypeMappings[
-        'org.bson.types.ObjectId'
-    ] = new SimpleType("string")
-
-    configuration.simpleTypeMappings[
-        'com.example.CustomId'
-    ] = new SimpleType(/* type */ "integer", /* format */ "int64")
-}
-```
-
-## Property Filters
-
-Control which properties are included in schemas:
-
-```groovy
-configuration.propertyInSchemeFilter = {
-    ctx, type, property ->
-        !property.simpleName
-            .toString()
-            .startsWith("internal")
-}
-```
-
-## Custom Type Processors
-
-Insert custom logic for handling specific types (e.g., unwrapping `AtomicReference<T>`):
-
-```groovy
-configuration.insertEmbeddedTypeProcessor({
-    EmbeddedTypeProcessorContext context ->
-        if (context.type.simpleName == 'AtomicReference'
-            && context.type.generics.size() == 1) {
-            context.parentContext.typeSchemaGenerator.addType(
-                context.scheme,
-                context.type.generics[0],
-                context.inlineRefs,
-                context.references,
-                false
-            )
-            return true // handled
-        }
-
-        return false // use default processing
-})
-```
-
-Custom type processors run before all built-in type processing, so they can override the default behavior for any type.
-
-## Debug Mode
-
-Enable debug output during annotation processing:
-
-```groovy
-configuration.debug = true
-```
-
-## Parser Validation
-
-Validate the generated specification with Swagger Parser:
-
-```groovy
-configuration.validateWithParser = true // default
-```
-
-## Full Example
-
-```groovy
-import io.javalin.openapi.experimental.*
-
-@ExperimentalCompileOpenApiConfiguration
-class OpenApiConfiguration
-    implements OpenApiAnnotationProcessorConfigurer {
-
-    @Override
-    void configure(
-        OpenApiAnnotationProcessorConfiguration configuration
-    ) {
-        configuration.simpleTypeMappings[
-            'org.bson.types.ObjectId'
-        ] = new SimpleType("string")
-
-        configuration.simpleTypeMappings[
-            'com.example.Money'
-        ] = new SimpleType("string")
-
-        configuration.propertyInSchemeFilter = {
-            ctx, type, property ->
-                !property.simpleName
-                    .toString()
-                    .startsWith("_")
-        }
-
-        configuration.debug = false
-        configuration.validateWithParser = true
-    }
-}
-```
+For custom type mappings, property filters, and custom type processors, see [Scripting Configuration](./scripting).

docs/advanced/runtime-builder.md

@@ -4,9 +4,9 @@ The `OpenApiSchemaBuilder` provides a Kotlin DSL for building and modifying Open
 
 ## When to Use
 
-- **Extend compile-time schemas** — add servers, security, or extra endpoints at startup
-- **Dynamic endpoints** — describe routes registered at runtime that the annotation processor can't see
-- **Testing** — build expected schemas in tests without JSON strings
+- **Extend compile-time schemas** - add servers, security, or extra endpoints at startup
+- **Dynamic endpoints** - describe routes registered at runtime that the annotation processor can't see
+- **Testing** - build expected schemas in tests without JSON strings
 
 ## Basic Usage
 
@@ -41,21 +41,21 @@ The `SchemaBuilder` DSL provides a clean way to define inline schemas without wo
 
 ```kotlin
 schema { type("string") }
-// → { "type": "string" }
+// -> { "type": "string" }
 ```
 
 ### Type with Format
 
 ```kotlin
 schema { type("integer"); format("int32") }
-// → { "type": "integer", "format": "int32" }
+// -> { "type": "integer", "format": "int32" }
 ```
 
 ### Reference
 
 ```kotlin
 schema { ref("#/components/schemas/User") }
-// → { "$ref": "#/components/schemas/User" }
+// -> { "$ref": "#/components/schemas/User" }
 ```
 
 The schema DSL is available on media types, parameters, headers, and object schema properties.
@@ -217,7 +217,67 @@ schema.path("/users").operation("get") {
 val json = schema.toJson()
 ```
 
-Reopening an existing operation preserves all fields — only the fields you set are changed. This makes it safe to layer runtime additions on top of compile-time output.
+Reopening an existing operation preserves all fields - only the fields you set are changed. This makes it safe to layer runtime additions on top of compile-time output.
+
+## Auto-generating Docs for Registered Routes
+
+For a springdoc-style experience - documenting routes that are registered programmatically (and that the compile-time processor never sees) - use the **dynamic hook** module. It adds undocumented Javalin routes to the served document.
+
+```kotlin [Gradle (Kotlin)]
+dependencies {
+    val openapi = "7.3.0-RC.1"
+    implementation("io.javalin.community.openapi:javalin-openapi-dynamic-hook:$openapi")
+}
+```
+
+Register `RegisteredRoutesHook` on the `OpenApiPlugin`:
+
+```kotlin
+Javalin.start { config ->
+    config.registerPlugin(OpenApiPlugin { it.withHook(RegisteredRoutesHook()) })
+
+    config.routes.get("/users") { /* ... */ }
+    config.routes.get("/users/{id}") { /* ... */ }
+}
+```
+
+Every newly discovered route is documented with its path, method, path parameters (typed as `string`), and a default `200` response. Existing operations from compile-time documentation are left unchanged unless the route carries runtime metadata.
+
+Routes registered by `OpenApiPlugin`, `SwaggerPlugin`, and `ReDocPlugin` are excluded by default, including custom UI and WebJar paths. Add prefix exclusions for your own non-API routes:
+
+```kotlin
+RegisteredRoutesHook { routes ->
+    routes.withIgnoredPathPrefixes("/assets", "/internal")
+}
+```
+
+Each prefix matches the path itself and its descendants, so `/assets` excludes `/assets/logo.svg` but not `/assets-admin`. A trailing `/*` is accepted as an equivalent spelling. To include the default excluded plugin routes, call `clearDefaultIgnoredRoutes()`.
+
+### Enriching a Route
+
+Javalin handlers are opaque lambdas, so without extra information the hook can only emit those stubs - it cannot infer request/response bodies. Attach an `OpenApiMetadata` to a route to describe it using the same operation DSL shown above; `schema(Class)` resolves the type through the reflection schema engine (no annotation processing required):
+
+```kotlin
+config.routes.addEndpoint(
+    Endpoint.create(HandlerType.GET, "/users/{id}")
+        .addMetadata(OpenApiMetadata {
+            summary("Get a user")
+            responses {
+                response("200") {
+                    description("The user")
+                    content { mediaType("application/json") { schema(User::class.java) } }
+                }
+            }
+        })
+        .handler { /* ... */ }
+)
+```
+
+For newly discovered operations, the path-parameter skeleton is auto-added before your metadata is applied. Existing operations retain their parameters, and referenced types (e.g. `User`) are emitted into `components/schemas`.
+
+::: warning
+The document is built on its first request, so routes registered after that request are not included. Runtime reflection cannot see CLASS-retention annotations or automatically discover discriminator subtypes. Runtime reflection is opt-in: it only happens when you add this module and register the hook, so the compile-time backends stay reflection-free.
+:::
 
 ## Merge Behavior