We recently wrote a backend with Kotlin + Jooby. T...

# dsl

[Marc Reichelt]

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:

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:

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:

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?

[Marc Reichelt]

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.