diff --git a/README.md b/README.md index 5046b7a..800eefe 100644 --- a/README.md +++ b/README.md @@ -11,11 +11,13 @@ * [Usage](#usage) * [Kotlin DSL](#kotlin-dsl-usage) * [Spring Web](#spring-web-usage) + * [Ktor](#ktor-usage) * [Annotation](#annotation-usage) * [Kotlin Script](#kotlin-script-usage) * [Examples](#examples) * [Configuration](#configuration) * [Spring Web](#spring-web-configuration) + * [Ktor](#ktor-configuration) * [Maven Plugin](#maven-plugin-configuration) * [License](#license) @@ -169,6 +171,66 @@ data class ChatMessage( ``` +### Ktor +To serve your AsyncAPI specification via Ktor: +- add the `kotlin-asyncapi-ktor` dependency +- install the `AsyncApiPlugin` in you application +- document your API with `AsyncApiExtension` and/or Kotlin scripting (see [Kotlin script usage](#kotlin-script-usage)) +- add annotations to auto-generate components (see [annotation usage](#annotation-usage)) + +You can register multiple extensions to extend and override AsyncAPI components. Extensions with a higher order override extensions with a lower order. Please note that you can only extend top-level components for now (`info`, `channels`, `servers`...). Subcomponents will always be overwritten. + +**Example** (simplified version of [Gitter example](https://github.com/asyncapi/spec/blob/22c6f2c7a61846338bfbd43d81024cb12cf4ed5f/examples/gitter-streaming.yml)) +```kotlin +fun main() { + embeddedServer(Netty, port = 8000) { + install(AsyncApiPlugin) { + extension = AsyncApiExtension.builder(order = 10) { + info { + title("Gitter Streaming API") + version("1.0.0") + } + servers { + // ... + } + // ... + } + } + }.start(wait = true) +} + +@Channel( + value = "/rooms/{roomId}", + parameters = [ + Parameter( + value = "roomId", + schema = Schema( + type = "string", + examples = ["53307860c3599d1de448e19d"] + ) + ) + ] +) +class RoomsChannel { + + @Subscribe(message = Message(ChatMessage::class)) + fun publish(/*...*/) { /*...*/ } +} + +@Message +data class ChatMessage( + val id: String, + val text: String +) +``` +```xml + + org.openfolder + kotlin-asyncapi-ktor + ${kotlin-asyncapi.version} + +``` + ### Annotation The `kotlin-asyncapi-annotation` module defines technology-agnostic annotations that can be used to document event-driven microservice APIs. @@ -191,6 +253,7 @@ You have two options to use Kotlin scripting in your project: ### Examples - [Spring Boot Application](kotlin-asyncapi-examples/kotlin-asyncapi-spring-boot-example) +- [Ktor Application](kotlin-asyncapi-examples/kotlin-asyncapi-ktor-example) #### Maven Plugin The Maven plugin evaluates your `asyncapi.kts` script, generates a valid AsyncAPI JSON file and adds it to the project resources. The `kotlin-asyncapi-spring-web` module picks the generated resource up and converts it to an `AsyncApiExtension`. @@ -261,14 +324,28 @@ In order to enable embedded scripting, you need to make some additional configur ### Spring Web You can configure the Spring Web integration in the application properties: -| Property | Description | Default | -|---------------------------------|---------------------------------------------------------------|----------------------------------------------| -| `asyncapi.enabled` | Enables the autoconfiguration | `true` | -| `asyncapi.path` | The resource path for serving the generated AsyncAPI document | `/docs/asyncapi` | -| `asyncapi.annotation.enabled` | Enables the annotation scanning and processing | `true` | -| `asyncapi.script.enabled` | Enables the Kotlin script support | `true` | -| `asyncapi.script.resource-path` | Path to the generated script resource file | `classpath:asyncapi/generated/asyncapi.json` | -| `asyncapi.script.source-path` | Path to the AsyncAPI Kotlin script file | `classpath:build.asyncapi.kts` | +| Property | Description | Default | +|---------------------------------|---------------------------------------------------------------|------------------------------------| +| `asyncapi.enabled` | Enables the autoconfiguration | `true` | +| `asyncapi.path` | The resource path for serving the generated AsyncAPI document | `/docs/asyncapi` | +| `asyncapi.annotation.enabled` | Enables the annotation scanning and processing | `true` | +| `asyncapi.script.enabled` | Enables the Kotlin script support | `true` | +| `asyncapi.script.resource-path` | Path to the generated script resource file | `asyncapi/generated/asyncapi.json` | +| `asyncapi.script.source-path` | Path to the AsyncAPI Kotlin script file | `build.asyncapi.kts` | + +### Ktor +You can configure the Ktor integration in the plugin configuration: + +| Property | Description | Default | +|-------------------|---------------------------------------------------------------|------------------------------------| +| `path` | The resource path for serving the generated AsyncAPI document | `/docs/asyncapi` | +| `baseClass` | The base class to filter code scanning packages | `null` | +| `scanAnnotations` | Enables class path scanning for annotations | `true` | +| `extension` | AsyncApiExtension hook | `AsyncApiExtension.empty()` | +| `extensions` | For registering multiple AsyncApiExtension hooks | `emptyList()` | +| `resourcePath` | Path to the generated script resource file | `asyncapi/generated/asyncapi.json` | +| `sourcePath` | Path to the AsyncAPI Kotlin script file | `build.asyncapi.kts` | + ### Maven Plugin You can configure the plugin in the plugin configuration: