For example, say we have endpoints that can all return some kind of error that needs to be documented on all of them. Provide a way to do something like this:

withDescription({
    418 response "application/json" {
       // ...
    }
}) {
    get("hello") {
        // ...
    } describe {
        // the response is automatically added here
    }
}

I have updated the dependencies and "migrated" everything to Ktor 2.

I just cant seem to get the swagger UI running Opening /swagger just displays an empty page.

Hi there!

TL;DR: Koa has been superseded by Tegral OpenAPI, which you can check out here

Thanks for your interest in Koa! Koa has been improved (including rewrites in a few places), properly documented and moved to the Tegral project. Please check it out here!

Advantages of Tegral OpenAPI over Koa include:

• More reliable class --> schema transformation (List<Something> now works properly)
• Actual releases to Maven Central
• A more complete DSL (still not fully complete but we're getting there)
• More tooling: the DSL can now be used fully standalone, including as a separate file *.openapi.kts, which can then be turned to a regular OpenAPI JSON or YAML file using the new CLI.
• Proper documentation. If you want to check out more, see here for the Tegral 0.0.2 release announcement, which includes details about Tegral OpenAPI.

In short, it's everything you know and love about Koa, but even better!

As a result, the Koa repository has been archived, as further development will only happen on the Tegral repository

Original message

Just a heads up for people interested in this project: I'll soon be migrating it under the Tegral repository, with proper integration into Tegral. This means that:

• This project will receive appropriate documentation support, both in the form of KDoc and regular documentation
• This project will be synced with the rest of Tegral libraries.

Note that you will not have to use everything from Tegral to use the OpenAPI capabilities. Just like the current Koa feature/plugin (and just like everything in Tegral), you'll be able to just add it like any other Ktor feature/plugin without anything else from the Tegral ecosystem.

Because Swagger UI uses relative links to resolve resources (like CSS, JS and images), going to /swagger will serve the correct index.html file, but the browser will call the wrong URLs when trying to resolve resources. A simple workaround is to trigger a 307 redirection from /swagger to /swagger/index.html if possible.

There is a potential trap here because I don't think Ktor has an easy way of specifying "redirect to this subroute", and we can only set a redirection to an absolute path.