{"id":25146414,"url":"https://github.com/asyncapi/kotlin-asyncapi","last_synced_at":"2026-01-25T12:03:40.553Z","repository":{"id":41511110,"uuid":"509940588","full_name":"asyncapi/kotlin-asyncapi","owner":"asyncapi","description":"Simplify event-driven API documentation for Kotlin microservices","archived":false,"fork":false,"pushed_at":"2025-04-14T18:49:53.000Z","size":9101,"stargazers_count":30,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-19T19:29:22.810Z","etag":null,"topics":["asyncapi","documentation","event-driven","java","kotlin","kotlin-asyncapi","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asyncapi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"asyncapi","patreon":null,"open_collective":"asyncapi","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2022-07-03T06:20:51.000Z","updated_at":"2025-04-14T18:44:36.000Z","dependencies_parsed_at":"2023-01-21T20:19:39.385Z","dependency_job_id":"bbb39526-a613-42f9-8e55-ca453bf00376","html_url":"https://github.com/asyncapi/kotlin-asyncapi","commit_stats":{"total_commits":69,"total_committers":3,"mean_commits":23.0,"dds":0.4057971014492754,"last_synced_commit":"f22cda2fde5a318be3288d39e6f9a69fc59fd9ab"},"previous_names":["openfolder/kotlin-asyncapi"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asyncapi%2Fkotlin-asyncapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asyncapi%2Fkotlin-asyncapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asyncapi%2Fkotlin-asyncapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asyncapi%2Fkotlin-asyncapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asyncapi","download_url":"https://codeload.github.com/asyncapi/kotlin-asyncapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251311697,"owners_count":21569080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncapi","documentation","event-driven","java","kotlin","kotlin-asyncapi","spring-boot"],"created_at":"2025-02-08T20:18:22.205Z","updated_at":"2025-10-18T14:56:19.495Z","avatar_url":"https://github.com/asyncapi.png","language":"Kotlin","funding_links":["https://github.com/sponsors/asyncapi","https://opencollective.com/asyncapi"],"categories":[],"sub_categories":[],"readme":"![Logo](.github/assets/kotlin_asyncapi_logo.png)\n[![Apache License 2](https://img.shields.io/badge/license-ASF2-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0.txt)\n[![Build status](https://github.com/asyncapi/kotlin-asyncapi/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/asyncapi/kotlin-asyncapi/actions/workflows/build.yml)\n[![Qodana](https://github.com/asyncapi/kotlin-asyncapi/actions/workflows/qodana.yml/badge.svg?branch=master)](https://asyncapi.github.io/kotlin-asyncapi/qodana/report)\n[![Maven Central status](https://img.shields.io/maven-central/v/org.openfolder/kotlin-asyncapi-parent.svg)](https://search.maven.org/#search%7Cga%7C1%7Corg.openfolder%20kotlin-asyncapi)\n\n\u003e [!NOTE]\n\u003e Spring Framework 6 / Spring Boot 3 is supported since `6.0.14` / `3.1.6`\n\n* [About](#about)\n* [Usage](#usage)\n    * [Kotlin DSL](#kotlin-dsl-usage)\n    * [Spring Web](#spring-web-usage)\n    * [Ktor](#ktor-usage)\n    * [Annotation](#annotation-usage)\n    * [Kotlin Script](#kotlin-script-usage)\n    * [Examples](#examples)\n* [Configuration](#configuration)\n    * [Spring Web](#spring-web-configuration)\n    * [Ktor](#ktor-configuration)\n    * [Maven Plugin](#maven-plugin-configuration)\n* [License](#license)\n\n## About\nThe Kotlin AsyncAPI project aims to provide convenience tools for generating and serving \n[AsyncAPI](https://www.asyncapi.com/) documentation. The core of this project is a \n[Kotlin DSL](https://kotlinlang.org/docs/type-safe-builders.html) for building the specification in a typesafe way. \nThe modules around that core build a framework for documenting asynchronous microservice APIs.\n\n## Usage\n### \u003ca name=\"kotlin-dsl-usage\"\u003e\u003c/a\u003eKotlin DSL\nThe `AsyncApi` class represents the root of the specification. It provides a static entry function `asyncApi` to the \nbuild scope.\n\n**Example** (simplified version of [Gitter example](https://github.com/asyncapi/spec/blob/22c6f2c7a61846338bfbd43d81024cb12cf4ed5f/examples/gitter-streaming.yml))\n```kotlin\nasyncApi {\n    info {\n        title(\"Gitter Streaming API\")\n        version(\"1.0.0\")\n    }\n    servers {\n        server(\"production\") {\n            url(\"https://stream.gitter.im/v1\")\n            protocol(\"https\")\n            protocolVersion(\"1.1\")\n            security {\n                requirement(\"httpBearerToken\" to emptyList())\n            }\n        }\n    }\n    channels {\n        channel(\"/rooms/{roomId}\") {\n            parameters {\n                parameter(\"roomId\") {\n                    description(\"Id of the Gitter room.\")\n                    schema {\n                        type(\"string\")\n                        examples(\"53307860c3599d1de448e19d\")\n                    }\n                }\n            }\n            subscribe {\n                messages {\n                    oneOf {\n                        reference {\n                            ref(\"#/components/messages/chatMessage\")\n                        }\n                        reference {\n                            ref(\"#/components/messages/heartbeat\")\n                        }\n                    }\n                }\n            }\n        }\n    }\n    components {\n        securitySchemes {\n            schema(\"httpBearerToken\") {\n                type(\"http\")\n                scheme(\"bearer\")\n            }\n        }\n        messages {\n            message(\"chatMessage\") {\n                summary(\"A message represents an individual chat message sent to a room.\")\n                payload {\n                    type(\"object\")\n                    properties {\n                        schema(\"id\") {\n                            type(\"string\")\n                            description(\"ID of the message.\")\n                        }\n                        schema(\"text\") {\n                            type(\"string\")\n                            description(\"Original message in plain-text/markdown.\")\n                        }\n                    }\n                }\n            }\n            message(\"heartbeat\") {\n                summary(\"Its purpose is to keep the connection alive.\")\n                payload {\n                    type(\"string\")\n                    enum(\"\\r\\n\")\n                }\n            }\n        }\n    }\n}\n```\n\n### \u003ca name=\"spring-web-usage\"\u003e\u003c/a\u003eSpring Web\nTo serve your AsyncAPI specification via Spring Web:\n- add the `kotlin-asyncapi-spring-web` dependency\n- enable the auto-configuration by annotating a configuration class with `@EnableAsyncApi`\n- document your API with `AsyncApiExtension` beans and/or Kotlin scripting (see [Kotlin script usage](#kotlin-script-usage))\n- add annotations to auto-generate components (see [annotation usage](#annotation-usage))\n\nYou 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.\n\n**Example** (simplified version of [Gitter example](https://github.com/asyncapi/spec/blob/22c6f2c7a61846338bfbd43d81024cb12cf4ed5f/examples/gitter-streaming.yml))\n```kotlin\n@EnableAsyncApi\n@Configuration\nclass AsyncApiConfiguration {\n    \n    @Bean\n    fun asyncApiExtension() =\n        AsyncApiExtension.builder(order = 10) {\n            info {\n                title(\"Gitter Streaming API\")\n                version(\"1.0.0\")\n            }\n            servers {\n                // ...\n            }\n            // ...\n        }\n}\n\n@Channel(\n    value = \"/rooms/{roomId}\",\n    parameters = [\n        Parameter(\n            value = \"roomId\",\n            schema = Schema(\n                type = \"string\",\n                examples = [\"53307860c3599d1de448e19d\"]\n            )\n        )\n    ]\n)\nclass RoomsChannel {\n\n    @Subscribe(message = Message(ChatMessage::class))\n    fun publish(/*...*/) { /*...*/ }\n}\n\n@Message\ndata class ChatMessage(\n    val id: String,\n    val text: String\n)\n```\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.openfolder\u003c/groupId\u003e\n  \u003cartifactId\u003ekotlin-asyncapi-spring-web\u003c/artifactId\u003e\n  \u003cversion\u003e${kotlin-asyncapi.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### \u003ca name=\"ktor-usage\"\u003e\u003c/a\u003eKtor\nTo serve your AsyncAPI specification via Ktor:\n- add the `kotlin-asyncapi-ktor` dependency\n- install the `AsyncApiPlugin` in you application\n- document your API with `AsyncApiExtension` and/or Kotlin scripting (see [Kotlin script usage](#kotlin-script-usage))\n- add annotations to auto-generate components (see [annotation usage](#annotation-usage))\n\nYou 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.\n\n**Example** (simplified version of [Gitter example](https://github.com/asyncapi/spec/blob/22c6f2c7a61846338bfbd43d81024cb12cf4ed5f/examples/gitter-streaming.yml))\n```kotlin\nfun main() {\n    embeddedServer(Netty, port = 8000) {\n        install(AsyncApiPlugin) {\n            extension = AsyncApiExtension.builder(order = 10) {\n                info {\n                    title(\"Gitter Streaming API\")\n                    version(\"1.0.0\")\n                }\n                servers {\n                    // ...\n                }\n                // ...\n            }\n        }\n    }.start(wait = true)\n}\n\n@Channel(\n    value = \"/rooms/{roomId}\",\n    parameters = [\n        Parameter(\n            value = \"roomId\",\n            schema = Schema(\n                type = \"string\",\n                examples = [\"53307860c3599d1de448e19d\"]\n            )\n        )\n    ]\n)\nclass RoomsChannel {\n\n    @Subscribe(message = Message(ChatMessage::class))\n    fun publish(/*...*/) { /*...*/ }\n}\n\n@Message\ndata class ChatMessage(\n    val id: String,\n    val text: String\n)\n```\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.openfolder\u003c/groupId\u003e\n  \u003cartifactId\u003ekotlin-asyncapi-ktor\u003c/artifactId\u003e\n  \u003cversion\u003e${kotlin-asyncapi.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### \u003ca name=\"annotation-usage\"\u003e\u003c/a\u003eAnnotation\nThe `kotlin-asyncapi-annotation` module defines technology-agnostic annotations that can be used to document event-driven microservice APIs. \n\n| Annotation        | Target   | Description                                                                                                                          |\n|-------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------|\n| Channel           | `class`  | Marks a class that represents a event channel. The value property defines the name of the channel.                                   |\n| Subscribe/Publish | `method` | Marks a method that represents a channel operation. The method must be defined inside a channel class.                               |\n| Message           | `class`  | Marks a class that represents a message. The value property can be used to reference a class that is annotated with this annotation. |\n| Schema            | `class`  | Marks a class that represents a schema. The value property can be used to reference a class that is annotated with this annotation.  |\n\n### \u003ca name=\"kotlin-script-usage\"\u003e\u003c/a\u003eKotlin Script\n[Kotlin scripting](https://github.com/Kotlin/KEEP/blob/b0c8a37db684eaf74bb1305f3c180b5d2537d787/proposals/scripting-support.md) allows us to execute a piece of code in a provided context. The IDE can still provide features like autocompletion and syntax highlighting. Furthermore, it provides the following benefits:\n- separate AsyncAPI documentation from application source code\n- focus on AsyncAPI content and don't worry about the build context or spring web integration\n- use AsyncAPI Kotlin DSL in Java projects\n\nYou have two options to use Kotlin scripting in your project:\n- [Plugin] let the Maven plugin evaluate the script during build time (recommended)\n- [Embedded] let your Spring Boot application evaluate the script at runtime\n\n### \u003ca name=\"examples\"\u003e\u003c/a\u003eExamples\n- [Spring Boot Application](kotlin-asyncapi-examples/kotlin-asyncapi-spring-boot-example)\n- [Ktor Application](kotlin-asyncapi-examples/kotlin-asyncapi-ktor-example)\n\n#### Maven Plugin\nThe 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`.\n\nBy default, the plugin expects the script to be named `build.asyncapi.kts` and placed in the project root. The script path and resource target path can be changed in the plugin configuration.\n\n**Example** (simplified version of [Gitter example](https://github.com/asyncapi/spec/blob/22c6f2c7a61846338bfbd43d81024cb12cf4ed5f/examples/gitter-streaming.yml))\n```kotlin\ninfo {\n    title(\"Gitter Streaming API\")\n    version(\"1.0.0\")\n}\n\nservers {\n    // ...\n}\n\n// ...\n```\n```xml\n\u003cplugin\u003e\n  \u003cgroupId\u003eorg.openfolder\u003c/groupId\u003e\n  \u003cartifactId\u003ekotlin-asyncapi-maven-plugin\u003c/artifactId\u003e\n  \u003cversion\u003e${kotlin-asyncapi.version}\u003c/version\u003e\n  \u003cexecutions\u003e\n    \u003cexecution\u003e\n      \u003cgoals\u003e\n        \u003cgoal\u003egenerateResources\u003c/goal\u003e\n      \u003c/goals\u003e\n    \u003c/execution\u003e\n  \u003c/executions\u003e\n\u003c/plugin\u003e\n```\n\n#### Embedded Scripting\nIf you can't use the Maven plugin for your project, you can also let your Spring Boot application evaluate the script at runtime.\n\nYou have to place your script in your `resources` folder. Similarly to the plugin, the `kotlin-asyncapi-spring-web` module will pick up the script and convert it to an `AsyncApiExtension`. By default, the library expects the script to be named `build.asyncapi.kts` and placed in the root of the `resources` folder. This can be changed in the application properties.\n\nIn order to enable embedded scripting, you need to make some additional configurations:\n- add `kotlin-scripting-jvm-host` to the classpath\n- unpack `kotlin-compiler-embeddable` from the Spring Boot executable JAR file\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eorg.jetbrains.kotlin\u003c/groupId\u003e\n  \u003cartifactId\u003ekotlin-scripting-jvm-host\u003c/artifactId\u003e\n  \u003cversion\u003e${kotlin.version}\u003c/version\u003e\n  \u003cscope\u003eruntime\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n```xml\n\u003cplugin\u003e\n  \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\n  \u003cartifactId\u003espring-boot-maven-plugin\u003c/artifactId\u003e\n  \u003cconfiguration\u003e\n    \u003crequiresUnpack\u003e\n      \u003cdependency\u003e\n        \u003cgroupId\u003eorg.jetbrains.kotlin\u003c/groupId\u003e\n        \u003cartifactId\u003ekotlin-compiler-embeddable\u003c/artifactId\u003e\n      \u003c/dependency\u003e\n    \u003c/requiresUnpack\u003e\n  \u003c/configuration\u003e\n\u003c/plugin\u003e\n```\n\n## Configuration\n### \u003ca name=\"spring-web-configuration\"\u003e\u003c/a\u003eSpring Web\nYou can configure the Spring Web integration in the application properties:\n\n| Property                        | Description                                                   | Default                            |\n|---------------------------------|---------------------------------------------------------------|------------------------------------|\n| `asyncapi.enabled`              | Enables the autoconfiguration                                 | `true`                             |\n| `asyncapi.path`                 | The resource path for serving the generated AsyncAPI document | `/docs/asyncapi`                   |\n| `asyncapi.annotation.enabled`   | Enables the annotation scanning and processing                | `true`                             |\n| `asyncapi.script.enabled`       | Enables the Kotlin script support                             | `true`                             |\n| `asyncapi.script.resource-path` | Path to the generated script resource file                    | `asyncapi/generated/asyncapi.json` |\n| `asyncapi.script.source-path`   | Path to the AsyncAPI Kotlin script file                       | `build.asyncapi.kts`               |\n\n### \u003ca name=\"ktor-configuration\"\u003e\u003c/a\u003eKtor\nYou can configure the Ktor integration in the plugin configuration:\n\n| Property          | Description                                                   | Default                            |\n|-------------------|---------------------------------------------------------------|------------------------------------|\n| `path`            | The resource path for serving the generated AsyncAPI document | `/docs/asyncapi`                   |\n| `baseClass`       | The base class to filter code scanning packages               | `null`                             |\n| `scanAnnotations` | Enables class path scanning for annotations                   | `true`                             |\n| `extension`       | AsyncApiExtension hook                                        | `AsyncApiExtension.empty()`        |\n| `extensions`      | For registering multiple AsyncApiExtension hooks              | `emptyList()`                      |\n| `resourcePath`    | Path to the generated script resource file                    | `asyncapi/generated/asyncapi.json` |\n| `sourcePath`      | Path to the AsyncAPI Kotlin script file                       | `build.asyncapi.kts`               |\n\n\n### \u003ca name=\"maven-plugin-configuration\"\u003e\u003c/a\u003eMaven Plugin\nYou can configure the plugin in the plugin configuration:\n\n| Parameter          | Description                                           | Default               |\n|--------------------|-------------------------------------------------------|-----------------------|\n| `sourcePath`       | The relative path to the Kotlin script                | `build.asyncapi.kts`  |\n| `targetPath`       | The relative path to the generated target resources   | `asyncapi/generated/` |\n| `packageResources` | Adds the generated resources to the package classpath | `true`                |\n\n## License\nKotlin AsyncAPI is Open Source software released under the\n[Apache 2.0 license](http://www.apache.org/licenses/LICENSE-2.0.html).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasyncapi%2Fkotlin-asyncapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasyncapi%2Fkotlin-asyncapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasyncapi%2Fkotlin-asyncapi/lists"}