Support for OpenAPIV2 and OpenAPIV3 language in plugins (#304)

Co-authored-by: nsimonides
flock-community · Dec 4, 2024 · 197b3f8 · 197b3f8
1 parent f5ee9a3
commit 197b3f8
Show file tree

Hide file tree

Showing 24 changed files with 140 additions and 45 deletions.
diff --git a/...itter/src/main/java/community/flock/wirespec/example/maven/custom/emit/CustomEmitter.java b/...itter/src/main/java/community/flock/wirespec/example/maven/custom/emit/CustomEmitter.java
@@ -25,6 +25,12 @@ public CustomEmitter(@NotNull Logger logger, boolean split) {
         super(logger, split);
     }
 
+    @NotNull
+    @Override
+    public String getSingleLineComment() {
+        return "//";
+    }
+
     @NotNull
     @Override
     public String emitName(@NotNull Definition definition) {

diff --git a/src/compiler/core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/Utils.kt b/src/compiler/core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/Utils.kt
@@ -16,4 +16,6 @@ fun String.removeJavaPrefix() = removePrefix("java.util.")
 
 fun String.removeAngularBrackets() = filterNot { it == '<' || it == '>' }
 
-fun String.removeCommasAndSpaces() = filterNot { it == ',' || it == ' '}
+fun String.removeCommasAndSpaces() = filterNot { it == ',' || it == ' ' }
+
+fun String.removeCommentMarkers(): String = removePrefix("/*").removeSuffix("*/").trim()
diff --git a/...ler/core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/JavaEmitter.kt b/...ler/core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/JavaEmitter.kt
@@ -45,10 +45,7 @@ open class JavaEmitter(
         is Union -> emit(identifier)
     }
 
-    override fun notYetImplemented() =
-        """// TODO("Not yet implemented")
-            |
-        """.trimMargin()
+    override val singleLineComment = "//"
 
     override fun emit(ast: AST): List<Emitted> =
         super.emit(ast).map { (typeName, result) ->

diff --git a/...r/core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/KotlinEmitter.kt b/...r/core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/KotlinEmitter.kt
@@ -47,10 +47,7 @@ open class KotlinEmitter(
         is Union -> emit(identifier)
     }
 
-    override fun notYetImplemented() =
-        """// TODO("Not yet implemented")
-            |
-        """.trimMargin()
+    override val singleLineComment = "//"
 
     override fun emit(ast: AST): List<Emitted> =
         super.emit(ast).map { (typeName, result) ->

diff --git a/...er/core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/ScalaEmitter.kt b/...er/core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/ScalaEmitter.kt
@@ -42,10 +42,7 @@ open class ScalaEmitter(
         is Union -> emit(identifier)
     }
 
-    override fun notYetImplemented() =
-        """// TODO("Not yet implemented")
-            |
-        """.trimMargin()
+    override val singleLineComment = "//"
 
     override fun emit(ast: AST): List<Emitted> =
         super.emit(ast).map { (typeName, result) ->

diff --git a/...re/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/TypeScriptEmitter.kt b/...re/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/TypeScriptEmitter.kt
@@ -3,7 +3,6 @@ package community.flock.wirespec.compiler.core.emit
 import community.flock.wirespec.compiler.core.emit.common.DefinitionModelEmitter
 import community.flock.wirespec.compiler.core.emit.common.Emitted
 import community.flock.wirespec.compiler.core.emit.common.Emitter
-import community.flock.wirespec.compiler.core.emit.common.Emitter.Companion.firstToLower
 import community.flock.wirespec.compiler.core.emit.common.Spacer
 import community.flock.wirespec.compiler.core.emit.shared.TypeScriptShared
 import community.flock.wirespec.compiler.core.parse.AST
@@ -31,10 +30,7 @@ open class TypeScriptEmitter(logger: Logger = noLogger) : DefinitionModelEmitter
         is Channel -> emit(identifier)
     }
 
-    override fun notYetImplemented() =
-        """// TODO("Not yet implemented")
-            |
-        """.trimMargin()
+    override val singleLineComment = "//"
 
     override fun emit(ast: AST): List<Emitted> =
         super.emit(ast).map {

diff --git a/...core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/WirespecEmitter.kt b/...core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/WirespecEmitter.kt
@@ -30,7 +30,9 @@ open class WirespecEmitter(logger: Logger = noLogger) : DefinitionModelEmitter,
         is Channel -> emit(identifier)
     }
 
-    override fun notYetImplemented() = "\n"
+    override val singleLineComment = "\n"
+
+    override fun notYetImplemented() = singleLineComment
 
     override fun emit(type: Type, ast: AST) = """
         |type ${emit(type.identifier)} {

diff --git a/.../core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/common/Emitter.kt b/.../core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/common/Emitter.kt
@@ -17,7 +17,7 @@ import community.flock.wirespec.compiler.utils.Logger
 
 abstract class Emitter(
     val logger: Logger,
-    val split: Boolean = false
+    val split: Boolean = false,
 ) : Emitters {
 
     data class Param(
@@ -31,9 +31,7 @@ abstract class Emitter(
         }
     }
 
-    abstract fun Definition.emitName(): String
-
-    abstract fun notYetImplemented(): String
+    open fun Definition.emitName(): String = notYetImplemented()
 
     open fun emit(ast: AST): List<Emitted> = ast
         .map {

diff --git a/...core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/common/Emitters.kt b/...core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/emit/common/Emitters.kt
@@ -16,7 +16,8 @@ interface Emitters :
     EndpointDefinitionEmitter,
     UnionDefinitionEmitter,
     IdentifierEmitter,
-    ChannelDefinitionEmitter
+    ChannelDefinitionEmitter,
+    NotYetImplemented
 
 interface TypeDefinitionEmitter {
     fun emit(type: Type, ast: AST): String
@@ -45,3 +46,8 @@ interface ChannelDefinitionEmitter {
 interface IdentifierEmitter {
     fun emit(identifier: Identifier): String
 }
+
+interface NotYetImplemented {
+    val singleLineComment: String
+    fun notYetImplemented() = "$singleLineComment TODO(\"Not yet implemented\")\n"
+}
diff --git a/src/compiler/core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/parse/Node.kt b/src/compiler/core/src/commonMain/kotlin/community/flock/wirespec/compiler/core/parse/Node.kt
@@ -2,6 +2,7 @@ package community.flock.wirespec.compiler.core.parse
 
 import community.flock.wirespec.compiler.core.Value
 import community.flock.wirespec.compiler.core.removeBackticks
+import community.flock.wirespec.compiler.core.removeCommentMarkers
 import kotlin.jvm.JvmInline
 
 sealed interface Node
@@ -112,7 +113,11 @@ data class Channel(
 ) : Definition
 
 @JvmInline
-value class Comment(override val value: String) : Value<String>
+value class Comment private constructor(override val value: String) : Value<String> {
+    companion object {
+        operator fun invoke(comment: String) = Comment(comment.removeCommentMarkers())
+    }
+}
 
 sealed class Identifier(name: String) : Value<String> {
     override val value = name.removeBackticks()

diff --git a/src/compiler/core/src/commonTest/kotlin/community/flock/wirespec/compiler/core/UtilsTest.kt b/src/compiler/core/src/commonTest/kotlin/community/flock/wirespec/compiler/core/UtilsTest.kt
@@ -33,4 +33,17 @@ class UtilsTest {
         "java.util.List<String>".concatGenerics() shouldBe "ListString"
     }
 
+    @Test
+    fun testRemoveCommentMarkers() {
+        "/* Simple comment */".removeCommentMarkers() shouldBe "Simple comment"
+        "/*    Padded    */".removeCommentMarkers() shouldBe "Padded"
+        "/**/".removeCommentMarkers() shouldBe ""
+
+        """/* Multiple
+           | Lines
+           | Here */""".trimMargin().removeCommentMarkers() shouldBe """Multiple
+           | Lines
+           | Here""".trimMargin()
+    }
+
 }
diff --git a/...iler/core/src/commonTest/kotlin/community/flock/wirespec/compiler/core/parse/ParseTest.kt b/...iler/core/src/commonTest/kotlin/community/flock/wirespec/compiler/core/parse/ParseTest.kt
@@ -84,15 +84,15 @@ class ParseTest {
     @Test
     fun testParserWithDoubleComment() {
         val source = """
-            |/**
-            | * This is comment 1
+            |/*
+            | This is comment 1
             | */
             |type Foo {
             |  foo: String
             |}
             |
-            |/**
-            | * This is comment 2
+            |/*
+            | This is comment 2
             | */
             |type Bar {
             |  bar: String
@@ -102,8 +102,8 @@ class ParseTest {
         WirespecSpec.tokenize(source)
             .let(parser()::parse)
             .shouldBeRight().filterIsInstance<Definition>().map { it.comment?.value } shouldBe listOf(
-            "/**\n * This is comment 1\n */",
-            "/**\n * This is comment 2\n */",
+            "This is comment 1",
+            "This is comment 2",
         )
     }
 }
diff --git a/src/converter/openapi/src/commonMain/kotlin/community/flock/wirespec/openapi/Common.kt b/src/converter/openapi/src/commonMain/kotlin/community/flock/wirespec/openapi/Common.kt
@@ -1,6 +1,7 @@
 package community.flock.wirespec.openapi
 
 import community.flock.wirespec.compiler.core.emit.common.Emitter.Companion.firstToUpper
+import kotlinx.serialization.json.Json
 
 object Common {
     fun className(vararg arg: String) = arg
@@ -9,4 +10,8 @@ object Common {
 
     fun <K, V> Map<K, V?>.filterNotNullValues(): Map<K, V> =
         mapNotNull { (key, value) -> value?.let { key to it } }.toMap()
+
+    val json = Json {
+        prettyPrint = true
+    }
 }
diff --git a/...ter/openapi/src/commonMain/kotlin/community/flock/wirespec/openapi/v2/OpenApiV2Emitter.kt b/...ter/openapi/src/commonMain/kotlin/community/flock/wirespec/openapi/v2/OpenApiV2Emitter.kt
@@ -14,19 +14,46 @@ import community.flock.kotlinx.openapi.bindings.v2.SchemaObject
 import community.flock.kotlinx.openapi.bindings.v2.SchemaOrReferenceObject
 import community.flock.kotlinx.openapi.bindings.v2.StatusCode
 import community.flock.kotlinx.openapi.bindings.v2.SwaggerObject
+import community.flock.wirespec.compiler.core.emit.common.Emitted
+import community.flock.wirespec.compiler.core.emit.common.Emitter
 import community.flock.wirespec.compiler.core.parse.AST
+import community.flock.wirespec.compiler.core.parse.Channel
 import community.flock.wirespec.compiler.core.parse.Endpoint
 import community.flock.wirespec.compiler.core.parse.Enum
 import community.flock.wirespec.compiler.core.parse.Field
+import community.flock.wirespec.compiler.core.parse.Identifier
 import community.flock.wirespec.compiler.core.parse.Reference
 import community.flock.wirespec.compiler.core.parse.Refined
 import community.flock.wirespec.compiler.core.parse.Type
+import community.flock.wirespec.compiler.core.parse.Union
+import community.flock.wirespec.compiler.utils.noLogger
+import community.flock.wirespec.openapi.Common.json
+import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.JsonPrimitive
 import community.flock.kotlinx.openapi.bindings.v2.Type as OpenApiType
 
-object OpenApiV2Emitter {
+object OpenApiV2Emitter: Emitter(noLogger) {
 
-    fun emit(ast: AST): SwaggerObject =
+    override val singleLineComment = ""
+
+    override fun emit(ast: AST): List<Emitted> =
+        listOf(Emitted("SwaggerObject", json.encodeToString(emitSwaggerObject(ast))))
+
+    override fun emit(type: Type, ast: AST) = notYetImplemented()
+
+    override fun emit(enum: Enum) = notYetImplemented()
+
+    override fun emit(refined: Refined) = notYetImplemented()
+
+    override fun emit(endpoint: Endpoint) = notYetImplemented()
+
+    override fun emit(union: Union) = notYetImplemented()
+
+    override fun emit(identifier: Identifier) = notYetImplemented()
+
+    override fun emit(channel: Channel) = notYetImplemented()
+
+    fun emitSwaggerObject(ast: AST): SwaggerObject =
         SwaggerObject(
             swagger = "2.0",
             info = InfoObject(
@@ -83,6 +110,7 @@ object OpenApiV2Emitter {
 
     private fun Endpoint.emit() = OperationObject(
         operationId = identifier.value,
+        description = comment?.value,
         consumes = requests.mapNotNull { it.content?.type }.distinct().ifEmpty { null },
         produces = responses.mapNotNull { it.content?.type }.distinct().ifEmpty { null },
         parameters = requests
@@ -103,7 +131,7 @@ object OpenApiV2Emitter {
         responses = responses
             .associate { response ->
                 StatusCode(response.status) to ResponseObject(
-                    description = "$identifier ${response.status} response",
+                    description = comment?.value ?: "${identifier.value} ${response.status} response",
                     headers = response.headers.associate {
                         it.identifier.value to HeaderObject(
                             type = it.reference.value,

diff --git a/...ter/openapi/src/commonMain/kotlin/community/flock/wirespec/openapi/v3/OpenApiV3Emitter.kt b/...ter/openapi/src/commonMain/kotlin/community/flock/wirespec/openapi/v3/OpenApiV3Emitter.kt
@@ -19,26 +19,51 @@ import community.flock.kotlinx.openapi.bindings.v3.ResponseObject
 import community.flock.kotlinx.openapi.bindings.v3.SchemaObject
 import community.flock.kotlinx.openapi.bindings.v3.SchemaOrReferenceObject
 import community.flock.kotlinx.openapi.bindings.v3.StatusCode
+import community.flock.wirespec.compiler.core.emit.common.Emitted
+import community.flock.wirespec.compiler.core.emit.common.Emitter
 import community.flock.wirespec.compiler.core.parse.AST
 import community.flock.wirespec.compiler.core.parse.Channel
 import community.flock.wirespec.compiler.core.parse.Definition
 import community.flock.wirespec.compiler.core.parse.Endpoint
 import community.flock.wirespec.compiler.core.parse.Enum
 import community.flock.wirespec.compiler.core.parse.Field
+import community.flock.wirespec.compiler.core.parse.Identifier
 import community.flock.wirespec.compiler.core.parse.Reference
 import community.flock.wirespec.compiler.core.parse.Refined
 import community.flock.wirespec.compiler.core.parse.Type
 import community.flock.wirespec.compiler.core.parse.Union
+import community.flock.wirespec.compiler.utils.noLogger
+import community.flock.wirespec.openapi.Common.json
+import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.JsonPrimitive
 import community.flock.kotlinx.openapi.bindings.v3.Type as OpenApiType
 
-object OpenApiV3Emitter {
+object OpenApiV3Emitter : Emitter(noLogger) {
     data class Options(
         val title: String,
-        val version: String
+        val version: String,
     )
 
-    fun emit(ast: AST, options: Options? = null) = OpenAPIObject(
+    override val singleLineComment = ""
+
+    override fun emit(ast: AST): List<Emitted> =
+        listOf(Emitted("OpenAPIObject", json.encodeToString(emitOpenAPIObject(ast, null))))
+
+    override fun emit(type: Type, ast: AST) = notYetImplemented()
+
+    override fun emit(enum: Enum) = notYetImplemented()
+
+    override fun emit(refined: Refined) = notYetImplemented()
+
+    override fun emit(endpoint: Endpoint) = notYetImplemented()
+
+    override fun emit(union: Union) = notYetImplemented()
+
+    override fun emit(identifier: Identifier) = notYetImplemented()
+
+    override fun emit(channel: Channel) = notYetImplemented()
+
+    fun emitOpenAPIObject(ast: AST, options: Options? = null) = OpenAPIObject(
         openapi = "3.0.0",
         info = InfoObject(
             title = options?.title ?: "Wirespec",
@@ -91,7 +116,7 @@ object OpenApiV3Emitter {
 
     private fun Type.emit(): SchemaObject =
         SchemaObject(
-
+            description = comment?.value,
             properties = shape.value.associate { it.emitSchema() },
             required = shape.value
                 .filter { !it.isNullable }
@@ -101,12 +126,14 @@ object OpenApiV3Emitter {
 
     private fun Enum.emit(): SchemaObject =
         SchemaObject(
+            description = comment?.value,
             type = OpenApiType.STRING,
             enum = entries.map { JsonPrimitive(it) }
         )
 
     private fun Union.emit(): SchemaObject =
         SchemaObject(
+            description = comment?.value,
             type = OpenApiType.STRING,
             oneOf = entries.map { it.emitSchema() }
         )
@@ -116,6 +143,7 @@ object OpenApiV3Emitter {
 
     private fun Endpoint.emit(): OperationObject = OperationObject(
         operationId = identifier.value,
+        description = comment?.value,
         parameters = path.filterIsInstance<Endpoint.Segment.Param>()
             .map { it.emitParameter() } + queries.map { it.emitParameter(ParameterLocation.QUERY) } + headers.map {
             it.emitParameter(
@@ -131,7 +159,7 @@ object OpenApiV3Emitter {
             .map { (statusCode, res) ->
                 StatusCode(statusCode) to ResponseObject(
                     headers = res.flatMap { it.headers }.associate { it.emitHeader() },
-                    description = "$identifier $statusCode response",
+                    description = "${identifier.value} $statusCode response",
                     content = res
                         .mapNotNull { it.content }
                         .associate { it.emit() }

diff --git a/...openapi/src/commonTest/kotlin/community/flock/wirespec/openapi/v2/OpenApiV2EmitterTest.kt b/...openapi/src/commonTest/kotlin/community/flock/wirespec/openapi/v2/OpenApiV2EmitterTest.kt
@@ -19,7 +19,7 @@ class OpenApiV2EmitterTest {
         val petstoreOpenAPi = OpenAPI.decodeFromString(petstoreJson)
         val petstoreAst = petstoreOpenAPi.parse()
 
-        val petstoreConvertedOpenApi = OpenApiV2Emitter.emit(petstoreAst)
+        val petstoreConvertedOpenApi = OpenApiV2Emitter.emitSwaggerObject(petstoreAst)
         val petstoreConvertedOpenAPiAst = petstoreConvertedOpenApi.parse()
 
         assertEquals(

diff --git a/...openapi/src/commonTest/kotlin/community/flock/wirespec/openapi/v3/OpenApiV3EmitterTest.kt b/...openapi/src/commonTest/kotlin/community/flock/wirespec/openapi/v3/OpenApiV3EmitterTest.kt
@@ -18,7 +18,7 @@ class OpenApiV3EmitterTest {
         val petstoreOpenAPi = OpenAPI.decodeFromString(petstoreJson)
         val petstoreAst = petstoreOpenAPi.parse()
 
-        val petstoreConvertedOpenAPi = OpenApiV3Emitter.emit(petstoreAst)
+        val petstoreConvertedOpenAPi = OpenApiV3Emitter.emitOpenAPIObject(petstoreAst, null)
         val petstoreConvertedOpenAPiAst = petstoreConvertedOpenAPi.parse()
 
         assertEquals(petstoreAst, petstoreConvertedOpenAPiAst)