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?