feat: support description on __Schema

kgraphql-ktor-stitched/api/kgraphql-ktor-stitched.api

@@ -348,15 +348,18 @@ public final class com/apurebase/kgraphql/stitched/schema/structure/Introspected
 
 public final class com/apurebase/kgraphql/stitched/schema/structure/IntrospectedSchema : com/apurebase/kgraphql/schema/introspection/__Schema {
 	public static final field Companion Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedSchema$Companion;
-	public fun <init> (Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Ljava/util/List;Ljava/util/List;)V
+	public fun <init> (Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Ljava/util/List;Ljava/util/List;Ljava/lang/String;)V
+	public synthetic fun <init> (Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Ljava/util/List;Ljava/util/List;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun component1 ()Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;
 	public final fun component2 ()Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;
 	public final fun component3 ()Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;
 	public final fun component4 ()Ljava/util/List;
 	public final fun component5 ()Ljava/util/List;
-	public final fun copy (Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Ljava/util/List;Ljava/util/List;)Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedSchema;
-	public static synthetic fun copy$default (Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedSchema;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Ljava/util/List;Ljava/util/List;ILjava/lang/Object;)Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedSchema;
+	public final fun component6 ()Ljava/lang/String;
+	public final fun copy (Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Ljava/util/List;Ljava/util/List;Ljava/lang/String;)Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedSchema;
+	public static synthetic fun copy$default (Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedSchema;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;Ljava/util/List;Ljava/util/List;Ljava/lang/String;ILjava/lang/Object;)Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedSchema;
 	public fun equals (Ljava/lang/Object;)Z
+	public fun getDescription ()Ljava/lang/String;
 	public fun getDirectives ()Ljava/util/List;
 	public synthetic fun getMutationType ()Lcom/apurebase/kgraphql/schema/introspection/__Type;
 	public fun getMutationType ()Lcom/apurebase/kgraphql/stitched/schema/structure/IntrospectedRootOperation;
@@ -545,11 +548,12 @@ public final class com/apurebase/kgraphql/stitched/schema/structure/StitchedProp
 }
 
 public final class com/apurebase/kgraphql/stitched/schema/structure/StitchedSchemaCompilation : com/apurebase/kgraphql/schema/structure/SchemaCompilation {
-	public fun <init> (Lcom/apurebase/kgraphql/stitched/schema/configuration/StitchedSchemaConfiguration;Lcom/apurebase/kgraphql/stitched/schema/structure/StitchedSchemaDefinition;)V
+	public fun <init> (Lcom/apurebase/kgraphql/stitched/schema/configuration/StitchedSchemaConfiguration;Lcom/apurebase/kgraphql/stitched/schema/structure/StitchedSchemaDefinition;Ljava/lang/String;)V
 	public synthetic fun getConfiguration ()Lcom/apurebase/kgraphql/configuration/SchemaConfiguration;
 	public fun getConfiguration ()Lcom/apurebase/kgraphql/stitched/schema/configuration/StitchedSchemaConfiguration;
 	public synthetic fun getDefinition ()Lcom/apurebase/kgraphql/schema/model/SchemaDefinition;
 	public fun getDefinition ()Lcom/apurebase/kgraphql/stitched/schema/structure/StitchedSchemaDefinition;
+	public final fun getLocalSchemaDescription ()Ljava/lang/String;
 	public fun perform (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 }
 

kgraphql-ktor-stitched/src/main/kotlin/com/apurebase/kgraphql/stitched/schema/dsl/StitchedSchemaBuilder.kt

@@ -45,7 +45,8 @@ class StitchedSchemaBuilder {
                 mergeSchemaDefinitions(
                     localSchemaBuilder.schemaDefinition,
                     model.toSchemaDefinition() as StitchedSchemaDefinition
-                )
+                ),
+                localSchemaBuilder.description
             ).perform()
         }
     }

kgraphql-ktor-stitched/src/main/kotlin/com/apurebase/kgraphql/stitched/schema/structure/IntrospectedSchema.kt

@@ -91,6 +91,7 @@ data class IntrospectedSchema(
     override val subscriptionType: IntrospectedRootOperation?,
     override val types: List<IntrospectedType>,
     override val directives: List<IntrospectedDirective>,
+    override val description: String? = null
 ) : __Schema {
     companion object {
         // Decoding the IntrospectionResponse must not fail when there are additional entries in the response, cf.

kgraphql-ktor-stitched/src/main/kotlin/com/apurebase/kgraphql/stitched/schema/structure/StitchedSchemaCompilation.kt

@@ -14,8 +14,9 @@ import com.apurebase.kgraphql.stitched.schema.configuration.StitchedSchemaConfig
 @ExperimentalAPI
 class StitchedSchemaCompilation(
     override val configuration: StitchedSchemaConfiguration,
-    override val definition: StitchedSchemaDefinition
-) : SchemaCompilation(configuration, definition) {
+    override val definition: StitchedSchemaDefinition,
+    val localSchemaDescription: String?
+) : SchemaCompilation(configuration, definition, localSchemaDescription) {
     private val remoteSchemaCompilation = RemoteSchemaCompilation(configuration)
 
     override suspend fun perform(): DefaultSchema {
@@ -105,7 +106,8 @@ class StitchedSchemaCompilation(
             // TODO: we shouldn't need to do a full recompilation again
             remoteTypesBySchema = definition.remoteSchemas.mapValues {
                 RemoteSchemaCompilation(configuration).perform(it.key, it.value)
-            }
+            },
+            description = localSchemaDescription // TODO: schemaDescription
         )
         val schema = DefaultSchema(configuration, model)
         schemaProxy.proxiedSchema = schema

kgraphql-ktor-stitched/src/test/kotlin/com/apurebase/kgraphql/stitched/schema/structure/StitchedSchemaTest.kt

@@ -42,8 +42,8 @@ class StitchedSchemaTest {
      * Executes the default introspection query against this [Schema] and returns it
      * as parsed [IntrospectedSchema]
      */
-    private fun Schema.introspected(): IntrospectedSchema {
-        val introspectionResponse = executeBlocking(Introspection.query())
+    private fun Schema.introspected(introspectionQuery: String = Introspection.query()): IntrospectedSchema {
+        val introspectionResponse = executeBlocking(introspectionQuery)
         return IntrospectedSchema.fromIntrospectionResponse(introspectionResponse)
     }
 
@@ -1210,4 +1210,58 @@ class StitchedSchemaTest {
 
         """.trimIndent()
     }
+
+    @Test
+    fun `stitched schema should support local schema description`() {
+        val schema = StitchedKGraphQL.stitchedSchema {
+            configure {
+                remoteExecutor = DummyRemoteRequestExecutor
+            }
+            localSchema {
+                description = "Local Schema"
+                query("localQuery") {
+                    resolver { -> LocalType("foo") }
+                }
+            }
+            remoteSchema("remote") {
+                getRemoteSchema {
+                    description = "Remote Schema (not shown)"
+                    query("remoteQuery") {
+                        description = "Remote Query"
+                        resolver { -> RemoteType(42) }
+                    }
+                }
+            }
+        }
+
+        val expectedSDL = """
+            "Local Schema"
+            schema {
+              query: Query
+            }
+
+            type LocalType {
+              value: String!
+            }
+
+            "Query object"
+            type Query {
+              localQuery: LocalType!
+              "Remote Query"
+              remoteQuery: RemoteType!
+            }
+
+            type RemoteType {
+              bar: Int!
+            }
+
+        """.trimIndent()
+
+        SchemaPrinter(
+            SchemaPrinterConfig(includeDescriptions = true, includeSchemaDefinition = true)
+        ).print(schema) shouldBe expectedSDL
+        SchemaPrinter(SchemaPrinterConfig(includeDescriptions = true, includeSchemaDefinition = true)).print(
+            schema.introspected(Introspection.query(Introspection.SpecLevel.WorkingDraft))
+        ) shouldBe expectedSDL
+    }
 }

kgraphql/api/kgraphql.api

@@ -144,6 +144,7 @@ public final class com/apurebase/kgraphql/schema/DefaultSchema : com/apurebase/k
 	public fun executeBlocking (Ljava/lang/String;Ljava/lang/String;Lcom/apurebase/kgraphql/Context;Ljava/lang/String;)Ljava/lang/String;
 	public fun findTypeByName (Ljava/lang/String;)Lcom/apurebase/kgraphql/schema/structure/Type;
 	public fun getConfiguration ()Lcom/apurebase/kgraphql/configuration/SchemaConfiguration;
+	public fun getDescription ()Ljava/lang/String;
 	public fun getDirectives ()Ljava/util/List;
 	public fun getMutationType ()Lcom/apurebase/kgraphql/schema/introspection/__Type;
 	public fun getQueryType ()Lcom/apurebase/kgraphql/schema/introspection/__Type;
@@ -508,13 +509,15 @@ public final class com/apurebase/kgraphql/schema/dsl/SchemaBuilder {
 	public final fun extendedScalars ()V
 	public final fun floatScalar (Lkotlin/reflect/KClass;Lkotlin/jvm/functions/Function1;)V
 	public final fun getConfiguration ()Lcom/apurebase/kgraphql/schema/dsl/SchemaConfigurationDSL;
+	public final fun getDescription ()Ljava/lang/String;
 	public final fun getSchemaDefinition ()Lcom/apurebase/kgraphql/schema/model/SchemaDefinition;
 	public final fun inputType (Lkotlin/reflect/KClass;Lkotlin/jvm/functions/Function1;)V
 	public final fun intScalar (Lkotlin/reflect/KClass;Lkotlin/jvm/functions/Function1;)V
 	public final fun longScalar (Lkotlin/reflect/KClass;Lkotlin/jvm/functions/Function1;)V
 	public final fun mutation (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Lcom/apurebase/kgraphql/schema/Publisher;
 	public final fun query (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Lcom/apurebase/kgraphql/schema/Publisher;
 	public final fun setConfiguration (Lcom/apurebase/kgraphql/schema/dsl/SchemaConfigurationDSL;)V
+	public final fun setDescription (Ljava/lang/String;)V
 	public final fun shortScalar (Lkotlin/reflect/KClass;Lkotlin/jvm/functions/Function1;)V
 	public final fun stringScalar (Lkotlin/reflect/KClass;Lkotlin/jvm/functions/Function1;)V
 	public final fun subscription (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)V
@@ -918,6 +921,7 @@ public final class com/apurebase/kgraphql/schema/introspection/SchemaProxy : com
 	public fun <init> ()V
 	public fun <init> (Lcom/apurebase/kgraphql/schema/introspection/__Schema;)V
 	public synthetic fun <init> (Lcom/apurebase/kgraphql/schema/introspection/__Schema;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun getDescription ()Ljava/lang/String;
 	public fun getDirectives ()Ljava/util/List;
 	public fun getMutationType ()Lcom/apurebase/kgraphql/schema/introspection/__Type;
 	public final fun getProxiedSchema ()Lcom/apurebase/kgraphql/schema/introspection/__Schema;
@@ -963,7 +967,7 @@ public abstract interface class com/apurebase/kgraphql/schema/introspection/__In
 	public abstract fun getType ()Lcom/apurebase/kgraphql/schema/introspection/__Type;
 }
 
-public abstract interface class com/apurebase/kgraphql/schema/introspection/__Schema {
+public abstract interface class com/apurebase/kgraphql/schema/introspection/__Schema : com/apurebase/kgraphql/schema/introspection/Describable {
 	public abstract fun getDirectives ()Ljava/util/List;
 	public abstract fun getMutationType ()Lcom/apurebase/kgraphql/schema/introspection/__Type;
 	public abstract fun getQueryType ()Lcom/apurebase/kgraphql/schema/introspection/__Type;
@@ -1554,8 +1558,9 @@ public final class com/apurebase/kgraphql/schema/model/ast/DefinitionNode$TypeSy
 }
 
 public final class com/apurebase/kgraphql/schema/model/ast/DefinitionNode$TypeSystemDefinitionNode$SchemaDefinitionNode : com/apurebase/kgraphql/schema/model/ast/DefinitionNode$TypeSystemDefinitionNode {
-	public fun <init> (Ljava/util/List;Ljava/util/List;Lcom/apurebase/kgraphql/schema/model/ast/Location;)V
-	public synthetic fun <init> (Ljava/util/List;Ljava/util/List;Lcom/apurebase/kgraphql/schema/model/ast/Location;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Ljava/util/List;Ljava/util/List;Lcom/apurebase/kgraphql/schema/model/ast/ValueNode$StringValueNode;Lcom/apurebase/kgraphql/schema/model/ast/Location;)V
+	public synthetic fun <init> (Ljava/util/List;Ljava/util/List;Lcom/apurebase/kgraphql/schema/model/ast/ValueNode$StringValueNode;Lcom/apurebase/kgraphql/schema/model/ast/Location;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun getDescription ()Lcom/apurebase/kgraphql/schema/model/ast/ValueNode$StringValueNode;
 	public final fun getDirectives ()Ljava/util/List;
 	public final fun getOperationTypes ()Ljava/util/List;
 }
@@ -2177,13 +2182,14 @@ public final class com/apurebase/kgraphql/schema/structure/RequestInterpreter {
 }
 
 public class com/apurebase/kgraphql/schema/structure/SchemaCompilation {
-	public fun <init> (Lcom/apurebase/kgraphql/configuration/SchemaConfiguration;Lcom/apurebase/kgraphql/schema/model/SchemaDefinition;)V
+	public fun <init> (Lcom/apurebase/kgraphql/configuration/SchemaConfiguration;Lcom/apurebase/kgraphql/schema/model/SchemaDefinition;Ljava/lang/String;)V
 	public fun getConfiguration ()Lcom/apurebase/kgraphql/configuration/SchemaConfiguration;
 	public fun getDefinition ()Lcom/apurebase/kgraphql/schema/model/SchemaDefinition;
 	protected final fun getEnums ()Ljava/util/Map;
 	protected final fun getInputTypeProxies ()Ljava/util/Map;
 	protected final fun getQueryTypeProxies ()Ljava/util/Map;
 	protected final fun getScalars ()Ljava/util/Map;
+	public final fun getSchemaDescription ()Ljava/lang/String;
 	protected final fun getSchemaProxy ()Lcom/apurebase/kgraphql/schema/introspection/SchemaProxy;
 	protected final fun getUnions ()Ljava/util/List;
 	protected final fun handleBaseTypes (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
@@ -2200,17 +2206,19 @@ public class com/apurebase/kgraphql/schema/structure/SchemaCompilation {
 }
 
 public final class com/apurebase/kgraphql/schema/structure/SchemaModel : com/apurebase/kgraphql/schema/introspection/__Schema {
-	public fun <init> (Lcom/apurebase/kgraphql/schema/structure/Type;Lcom/apurebase/kgraphql/schema/structure/Type;Lcom/apurebase/kgraphql/schema/structure/Type;Ljava/util/List;Ljava/util/Map;Ljava/util/Map;Ljava/util/List;Ljava/util/Map;)V
+	public fun <init> (Lcom/apurebase/kgraphql/schema/structure/Type;Lcom/apurebase/kgraphql/schema/structure/Type;Lcom/apurebase/kgraphql/schema/structure/Type;Ljava/util/List;Ljava/util/Map;Ljava/util/Map;Ljava/util/List;Ljava/util/Map;Ljava/lang/String;)V
 	public final fun component4 ()Ljava/util/List;
 	public final fun component5 ()Ljava/util/Map;
 	public final fun component6 ()Ljava/util/Map;
 	public final fun component7 ()Ljava/util/List;
 	public final fun component8 ()Ljava/util/Map;
-	public final fun copy (Lcom/apurebase/kgraphql/schema/structure/Type;Lcom/apurebase/kgraphql/schema/structure/Type;Lcom/apurebase/kgraphql/schema/structure/Type;Ljava/util/List;Ljava/util/Map;Ljava/util/Map;Ljava/util/List;Ljava/util/Map;)Lcom/apurebase/kgraphql/schema/structure/SchemaModel;
-	public static synthetic fun copy$default (Lcom/apurebase/kgraphql/schema/structure/SchemaModel;Lcom/apurebase/kgraphql/schema/structure/Type;Lcom/apurebase/kgraphql/schema/structure/Type;Lcom/apurebase/kgraphql/schema/structure/Type;Ljava/util/List;Ljava/util/Map;Ljava/util/Map;Ljava/util/List;Ljava/util/Map;ILjava/lang/Object;)Lcom/apurebase/kgraphql/schema/structure/SchemaModel;
+	public final fun component9 ()Ljava/lang/String;
+	public final fun copy (Lcom/apurebase/kgraphql/schema/structure/Type;Lcom/apurebase/kgraphql/schema/structure/Type;Lcom/apurebase/kgraphql/schema/structure/Type;Ljava/util/List;Ljava/util/Map;Ljava/util/Map;Ljava/util/List;Ljava/util/Map;Ljava/lang/String;)Lcom/apurebase/kgraphql/schema/structure/SchemaModel;
+	public static synthetic fun copy$default (Lcom/apurebase/kgraphql/schema/structure/SchemaModel;Lcom/apurebase/kgraphql/schema/structure/Type;Lcom/apurebase/kgraphql/schema/structure/Type;Lcom/apurebase/kgraphql/schema/structure/Type;Ljava/util/List;Ljava/util/Map;Ljava/util/Map;Ljava/util/List;Ljava/util/Map;Ljava/lang/String;ILjava/lang/Object;)Lcom/apurebase/kgraphql/schema/structure/SchemaModel;
 	public fun equals (Ljava/lang/Object;)Z
 	public final fun getAllTypes ()Ljava/util/List;
 	public final fun getAllTypesByName ()Ljava/util/Map;
+	public fun getDescription ()Ljava/lang/String;
 	public fun getDirectives ()Ljava/util/List;
 	public final fun getInputTypes ()Ljava/util/Map;
 	public synthetic fun getMutationType ()Lcom/apurebase/kgraphql/schema/introspection/__Type;

kgraphql/src/main/kotlin/com/apurebase/kgraphql/request/Introspection.kt

@@ -141,6 +141,7 @@ object Introspection {
             """
             query IntrospectionQuery {
               __schema {
+                description
                 queryType { name }
                 mutationType { name }
                 subscriptionType { name }

kgraphql/src/main/kotlin/com/apurebase/kgraphql/request/Parser.kt

@@ -607,6 +607,7 @@ internal class Parser {
      */
     private fun parseSchemaDefinition(): DefinitionNode.TypeSystemDefinitionNode.SchemaDefinitionNode {
         val start = lexer.token
+        val description = parseDescription()
         expectKeyword("schema")
         val directives = parseDirectives(true)
         val operationTypes = many(
@@ -617,6 +618,7 @@ internal class Parser {
         return DefinitionNode.TypeSystemDefinitionNode.SchemaDefinitionNode(
             directives = directives,
             operationTypes = operationTypes,
+            description = description,
             loc = loc(start)
         )
     }

kgraphql/src/main/kotlin/com/apurebase/kgraphql/schema/SchemaPrinter.kt

@@ -70,6 +70,7 @@ class SchemaPrinter(private val config: SchemaPrinterConfig = SchemaPrinterConfi
         //   https://spec.graphql.org/draft/#sec-Root-Operation-Types.Default-Root-Operation-Type-Names
         val schemaDefinition = if (includeSchemaDefinition(schema)) {
             buildString {
+                appendDescription(schema)
                 appendLine("schema {")
                 val indentation = "  "
                 // The query root operation type must always be provided

kgraphql/src/main/kotlin/com/apurebase/kgraphql/schema/dsl/SchemaBuilder.kt

@@ -42,9 +42,11 @@ class SchemaBuilder {
 
     var configuration = SchemaConfigurationDSL()
 
+    var description: String? = null
+
     fun build(): Schema {
         return runBlocking {
-            SchemaCompilation(configuration.build(), schemaDefinition).perform()
+            SchemaCompilation(configuration.build(), schemaDefinition, description).perform()
         }
     }
 

kgraphql/src/main/kotlin/com/apurebase/kgraphql/schema/introspection/SchemaProxy.kt

@@ -26,4 +26,7 @@ class SchemaProxy(
 
     override val directives: List<__Directive>
         get() = getProxied().directives
+
+    override val description: String?
+        get() = getProxied().description
 }

kgraphql/src/main/kotlin/com/apurebase/kgraphql/schema/introspection/__Schema.kt

@@ -1,6 +1,6 @@
 package com.apurebase.kgraphql.schema.introspection
 
-interface __Schema {
+interface __Schema : Describable {
     val types: List<__Type>
 
     val queryType: __Type

kgraphql/src/main/kotlin/com/apurebase/kgraphql/schema/model/ast/DefinitionNode.kt

@@ -37,6 +37,7 @@ sealed class DefinitionNode(override val loc: Location?) : ASTNode() {
         class SchemaDefinitionNode(
             val directives: List<DirectiveNode> = listOf(),
             val operationTypes: List<OperationTypeDefinitionNode>,
+            val description: StringValueNode?,
             loc: Location?
         ) : TypeSystemDefinitionNode(loc)