https://kotlinlang.org logo
#dsl
Title
# dsl
m

Marc Reichelt

01/03/2018, 4:40 PM
We recently wrote a backend with Kotlin + Jooby. To have good documentation we used swagger.io - but we had to write our
swagger.yaml
file ourselves. Using https://editor.swagger.io/ eased the pain, especially since it provides validation errors and code completion. Now I wonder whether I could write a Kotlin DSL for OpenAPI, and generate the
swagger.yaml
on the fly. So the initial results look tempting, as I can write:
Copy code
openapi {
    openapi { "3.0.1" }
    info {
        title { "Swagger Petstore" }
        version { "1.0.0" }
    }
}
But there are two things I dislike with this solution. One: I have to write a lot of code to get this basic functionality. And two: Nobody prevents me from calling
info
or
title
multiple times, or even omitting them totally. For example, this would be invalid:
Copy code
openapi {
    info {
        title { "Swagger Petstore" }
        title { "Swagger Petstore 2" }
        version { "1.0.0" }
    }
}
In contrast, writing the OpenAPI spec with data classes gains me more functionality than writing a custom DSL:
Copy code
Document(
        openapi = "3.0.1",
        info = Info(
                title = "Swagger Petstore",
                version = "1.0.0"
        )
)
Here I have to add
openapi
and
info
because they are both required, and IntelliJ tells me if there is a duplication error. So my question is: What do I gain from writing a DSL in this case, or is the OpenAPI spec not a good use case for it?
By the way: https://github.com/Kotlin/kotlinx.html is suffering from the same issues. I can omit tags like
body
and
head
, and I can write them multiple times as well.
👍 1
15 Views