{"id":13769835,"url":"https://github.com/ermadmi78/kobby","last_synced_at":"2025-04-06T09:11:08.978Z","repository":{"id":46531787,"uuid":"304932615","full_name":"ermadmi78/kobby","owner":"ermadmi78","description":"Kobby is a codegen plugin of Kotlin DSL Client by GraphQL schema. The generated DSL supports execution of complex GraphQL queries, mutation and subscriptions in Kotlin with syntax similar to native GraphQL syntax.","archived":false,"fork":false,"pushed_at":"2025-03-23T12:27:39.000Z","size":2554,"stargazers_count":84,"open_issues_count":4,"forks_count":5,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-30T08:11:43.854Z","etag":null,"topics":["client","code-generation","dsl","gradle","gradle-plugin","graphql","graphql-client","graphql-schema","graphql-subscriptions","kotlin","kotlin-dsl","kotlin-multiplatform","kotlin-native","maven","maven-plugin","multiplatform","plugin"],"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/ermadmi78.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-17T17:29:21.000Z","updated_at":"2025-03-14T16:23:55.000Z","dependencies_parsed_at":"2025-02-27T05:10:35.606Z","dependency_job_id":"5376bf45-5a81-4635-b056-e4f776cfa234","html_url":"https://github.com/ermadmi78/kobby","commit_stats":{"total_commits":328,"total_committers":4,"mean_commits":82.0,"dds":0.009146341463414642,"last_synced_commit":"bdce886fafd0d95655a8dfe80bb6974a20986518"},"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermadmi78%2Fkobby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermadmi78%2Fkobby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermadmi78%2Fkobby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ermadmi78%2Fkobby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ermadmi78","download_url":"https://codeload.github.com/ermadmi78/kobby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247457803,"owners_count":20941906,"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":["client","code-generation","dsl","gradle","gradle-plugin","graphql","graphql-client","graphql-schema","graphql-subscriptions","kotlin","kotlin-dsl","kotlin-multiplatform","kotlin-native","maven","maven-plugin","multiplatform","plugin"],"created_at":"2024-08-03T17:00:32.031Z","updated_at":"2025-04-06T09:11:08.957Z","avatar_url":"https://github.com/ermadmi78.png","language":"Kotlin","readme":"[![License](https://img.shields.io/badge/License-Apache%202.0-brightgreen)](https://github.com/ermadmi78/kobby/blob/main/LICENSE)\n[![Plugin Portal](https://img.shields.io/badge/Plugin%20Portal-v4.1.1-orange)](https://plugins.gradle.org/plugin/io.github.ermadmi78.kobby)\n[![Maven Central](https://img.shields.io/badge/Maven%20Central-v4.1.1-orange)](https://search.maven.org/artifact/io.github.ermadmi78/kobby-maven-plugin)\n[![Discussions](https://img.shields.io/badge/Discussions-On%20GitHub-blue)](https://github.com/ermadmi78/kobby/discussions)\n\n[![alt text](https://github.com/ermadmi78/kobby/blob/main/images/simple_query.png)](https://github.com/ermadmi78/kobby/wiki)\n\nKobby is a codegen plugin of Kotlin DSL Client by GraphQL schema. The generated DSL supports execution of complex\nGraphQL queries, mutations and subscriptions in Kotlin with syntax similar to native GraphQL syntax. Moreover, you can\ncustomize generated DSL by means of GraphQL schema directives and Kotlin extension functions.\n\n### Documentation\n\n* [Kobby Documentation](https://github.com/ermadmi78/kobby/wiki)\n\n### Tutorials\n\n* [How to generate Kotlin DSL Client by GraphQL schema](https://blog.kotlin-academy.com/how-to-generate-kotlin-dsl-client-by-graphql-schema-707fd0c55284)\n* [Генерируем Kotlin клиент по GraphQL схеме](https://habr.com/ru/articles/587388/)\n* [Kobby Gradle Tutorial](https://github.com/ermadmi78/kobby-gradle-tutorial)\n* [Kobby Maven Tutorial](https://github.com/ermadmi78/kobby-maven-tutorial)\n\n### Kotlin Multiplatform\n\nKobby [supports](https://github.com/ermadmi78/kobby/wiki/Gradle-Kotlinx-Serialization-Support) Kotlinx Serialization\nto provide an ability to generate Kotlin Multiplatform GraphQL DSL Client since\nrelease [3.0.0](https://github.com/ermadmi78/kobby/releases/tag/3.0.0).\n\n### Requirements\n\n#### Kobby 4.x.x\n\n* Gradle at least version 8.0 is required.\n* Maven at least version 3.9.1 is required.\n* Kotlin at least version 1.8.0 is required to compile generated client DSL (use Kobby at least [4.0.1](https://github.com/ermadmi78/kobby/releases/tag/4.0.1) for Kotlin 2.x).\n* Kotlinx Serialization at least version 1.5.0 is required.\n* Ktor at least version 2.0.0 is required to generate default adapters.\n* [graphql-ws](https://github.com/enisdenjo/graphql-ws) GraphQL Websocket protocol.\n\n#### Kobby 3.x.x\n\n* Gradle at least version 8.0 is required.\n* Maven at least version 3.9.1 is required.\n* Kotlin at least version 1.8.0 is required to compile generated client DSL.\n* Kotlinx Serialization at least version 1.5.0 is required.\n* Ktor at least version 2.0.0 is required to generate default adapters.\n* [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) GraphQL Websocket protocol (is legacy now).\n\n#### Kobby 2.x.x\n\n* Gradle at least version 7.0 is required.\n* Maven at least version 3.6.3 is required.\n* Kotlin at least version 1.6 is required to compile generated client DSL.\n* Ktor at least version 2.0.0 is required to generate default adapters.\n* [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) GraphQL Websocket protocol (is legacy now).\n\n#### Kobby 1.x.x\n\n* Gradle at least version 7.0 is required.\n* Maven at least version 3.6.3 is required.\n* Kotlin at least version 1.5 is required to compile generated client DSL.\n* 1.5.0 \u003c= Ktor version \u003c 2.0.0 is required to generate default adapters.\n* [subscriptions-transport-ws](https://github.com/apollographql/subscriptions-transport-ws) GraphQL Websocket protocol (is legacy now).\n\n### Contributing\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Gradle\n\n```kotlin\nplugins {\n    id(\"io.github.ermadmi78.kobby\") version \"4.1.1\"\n}\n```\n\n### Maven\n\n```xml\n\n\u003cbuild\u003e\n    \u003cplugins\u003e\n        \u003cplugin\u003e\n            \u003cgroupId\u003eio.github.ermadmi78\u003c/groupId\u003e\n            \u003cartifactId\u003ekobby-maven-plugin\u003c/artifactId\u003e\n            \u003cversion\u003e4.1.1\u003c/version\u003e\n            \u003cexecutions\u003e\n                \u003cexecution\u003e\n                    \u003cphase\u003egenerate-sources\u003c/phase\u003e\n                    \u003cgoals\u003e\n                        \u003cgoal\u003egenerate-kotlin\u003c/goal\u003e\n                    \u003c/goals\u003e\n                \u003c/execution\u003e\n            \u003c/executions\u003e\n        \u003c/plugin\u003e\n    \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\n### Define your GraphQL schema\n\nPut your GraphQL schema file in the project resources with `graphqls` extension. For example, let define\n[cinema.graphqls](https://github.com/ermadmi78/kobby-gradle-example/blob/main/cinema-api/src/main/resources/io/github/ermadmi78/kobby/cinema/api/cinema.graphqls)\nschema file and put it in `src/main/resources/io/github/ermadmi78/kobby/cinema/api/`\n\n### Configure Kobby Gradle plugin\n\n* Add Kobby plugin to your `build.gradle.kts`, to generate Kotlin DSL.\n* Configure Kotlin data types for scalars, defined in the GraphQL schema (more details about the scalar mapping\n  see [here](https://github.com/ermadmi78/kobby/wiki/Gradle-GraphQL-Scalar-Mapping)).\n* Add Jackson dependency to enable Jackson serialization or\n  configure [Kotlinx Serialization](https://github.com/ermadmi78/kobby/wiki/Gradle-Kotlinx-Serialization-Support).\n* Add Kotlin plugin to your `build.gradle.kts` to compile generated DSL.\n\n```kotlin\nimport io.github.ermadmi78.kobby.kobby\n\ndescription = \"Cinema API Example\"\n\nplugins {\n    kotlin(\"jvm\")\n    `java-library`\n    id(\"io.github.ermadmi78.kobby\")\n}\n\nkobby {\n    kotlin {\n        scalars = mapOf(\n            \"Date\" to typeOf(\"java.time\", \"LocalDate\"),\n            \"JSON\" to typeMap.parameterize(typeString, typeAny.nullable())\n        )\n    }\n}\n\nval jacksonVersion: String by project\ndependencies {\n    compileOnly(\"com.fasterxml.jackson.core:jackson-annotations:$jacksonVersion\")\n}\n```\n\n### Generate Kotlin DSL Client by your GraphQL schema\n\nExecute `gradle build` command to generate Kotlin DSL Client. The entry point of the DSL will be placed in\nthe `cinema.kt` file (name of the DSL entry point file is the same as the name of GraphQL schema file):\n\n[![alt text](https://github.com/ermadmi78/kobby/blob/main/images/cinema_api.png)](https://github.com/ermadmi78/kobby/wiki/Gradle-DSL-entry-point-configuration)\n\nMore details about the entry point configuration see\n[here](https://github.com/ermadmi78/kobby/wiki/Gradle-DSL-entry-point-configuration).\n\n### Instantiate DSL Context\n\nThe `cinema.kt` file will contain the `cinemaContextOf` builder function, which creates instance of the `CinemaContext`\ninterface - the entry point of the generated DSL. Note that the prefixes of the builder function, adapter and context\ninterfaces are the same as the name of the GraphQL schema file.\n\n```kotlin\nfun cinemaContextOf(adapter: CinemaAdapter): CinemaContext = CinemaContextImpl(adapter)\n```\n\nMore details about the DSL context see\n[here](https://github.com/ermadmi78/kobby/wiki/Overview-of-generated-GraphQL-DSL)\n\nWe have to pass instance of the `CinemaAdapter` interface to the `cinemaContextOf` function to create instance of\nthe `CinemaContext` interface. By default, Kobby does not generate any adapter implementations. But we can ask Kobby to\ngenerate default [Ktor](https://ktor.io/) implementations of the `CinemaAdapter` interface.\n\nTo do this just add `io.ktor:ktor-client-cio` dependency to you project:\n\n```kotlin\nval jacksonVersion: String by project\nval ktorVersion: String by project\ndependencies {\n    // Add this dependency to enable Jackson annotation generation in DTO classes by Kobby\n    compileOnly(\"com.fasterxml.jackson.core:jackson-annotations:$jacksonVersion\")\n\n    // Add this dependency to enable default Ktor adapters generation\n    compileOnly(\"io.ktor:ktor-client-cio:$ktorVersion\")\n}\n```\n\nRebuild the project, and Kobby will generate classes `CinemaSimpleKtorAdapter` and `CinemaCompositeKtorAdapter`\nin subpackage `adapter.ktor`. The prefix `\u003cCinema\u003e` by default is the schema name.\n\nHow to set up adapters for `Kotlinx Serialization` you can\nsee [here](https://github.com/ermadmi78/kobby/wiki/Gradle-Kotlinx-Serialization-Support).\n\nThe `CinemaSimpleKtorAdapter` is simple to configure, but it does not support GraphQL subscriptions - so we can use only\nqueries and mutations:\n\n```kotlin\nval client = HttpClient(CIO) {\n    install(ContentNegotiation) {\n        jackson {\n            registerModule(ParameterNamesModule(JsonCreator.Mode.PROPERTIES))\n            registerModule(JavaTimeModule())\n            // Force Jackson to serialize dates as String\n            disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)\n        }\n    }\n}\n\nval context = cinemaContextOf(CinemaSimpleKtorAdapter(client, \"http://localhost:8080/graphql\"))\n```\n\nThe `CinemaCompositeKtorAdapter` is more difficult to configure, but it supports all types of GraphQL operations,\nincluding subscriptions:\n\n```kotlin\nval client = HttpClient(CIO) {\n    install(WebSockets)\n}\n\nval mapper = jacksonObjectMapper()\n    .registerModule(ParameterNamesModule(JsonCreator.Mode.PROPERTIES))\n    .registerModule(JavaTimeModule())\n    // Force Jackson to serialize dates as String\n    .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)\n\nval context = cinemaContextOf(\n    CinemaCompositeKtorAdapter(\n        client,\n        \"http://localhost:8080/graphql\",\n        \"ws://localhost:8080/graphql\",\n        object : CinemaMapper {\n            override fun serialize(value: Any): String =\n                mapper.writeValueAsString(value)\n\n            override fun \u003cT : Any\u003e deserialize(content: String, contentType: KClass\u003cT\u003e): T =\n                mapper.readValue(content, contentType.java)\n        }\n    )\n)\n```\n\nSee [here](https://github.com/ermadmi78/kobby-gradle-example/blob/main/cinema-kotlin-client/src/main/kotlin/io/github/ermadmi78/kobby/cinema/kotlin/client/application.kt)\nfull example of adapters configuration. Note that you are not required to use the default adapters. You can write your\nown adapter implementation.\n\n### Ok, we are ready to execute GraphQL queries by means of generated Kotlin DSL Client\n\n#### Simple query\n\n[![alt text](https://github.com/ermadmi78/kobby/blob/main/images/simple_query.png)](https://github.com/ermadmi78/kobby/wiki/Overview-of-generated-GraphQL-DSL)\n\nYou can see more details about GraphQL queries support\n[here](https://github.com/ermadmi78/kobby/wiki/Overview-of-generated-GraphQL-DSL)\n\n#### Simple mutation\n\n[![alt text](https://github.com/ermadmi78/kobby/blob/main/images/mutation.png)](https://github.com/ermadmi78/kobby/wiki/Overview-of-generated-GraphQL-DSL)\n\n#### Simple subscription\n\n[![alt text](https://github.com/ermadmi78/kobby/blob/main/images/subscription.png)](https://github.com/ermadmi78/kobby/wiki/Support-for-GraphQL-subscriptions)\n\nYou can see more details about GraphQL subscriptions support\n[here](https://github.com/ermadmi78/kobby/wiki/Support-for-GraphQL-subscriptions)\n\n#### We can download a complex graph of objects by means of our Kotlin DSL\n\n[![alt text](https://github.com/ermadmi78/kobby/blob/main/images/complex_query.png)](https://github.com/ermadmi78/kobby/wiki/Overview-of-generated-GraphQL-DSL)\n\n#### GraphQL's unions and interfaces are supported too\n\n[![alt text](https://github.com/ermadmi78/kobby/blob/main/images/union_query.png)](https://github.com/ermadmi78/kobby/wiki/Support-for-GraphQL-Abstract-Data-Types)\n\nYou can see more details about GraphQL abstract data types support\n[here](https://github.com/ermadmi78/kobby/wiki/Support-for-GraphQL-Abstract-Data-Types)\n\n### License\n\n[Apache License Version 2.0](https://github.com/ermadmi78/kobby/blob/main/LICENSE)","funding_links":[],"categories":["Implementations","Schema Libraries"],"sub_categories":["Kotlin","Schema First"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fermadmi78%2Fkobby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fermadmi78%2Fkobby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fermadmi78%2Fkobby/lists"}