Add Ktor 2 Support about kompendium HOT 12 CLOSED

pre-pre-pre-pre-alpha sneak peek 👀

    routing {
      route("/") {
        rootDocumentation()
        get {
          call.respondText("Hello, world!")
        }
        route("/nesty") {
          nestyDocumentation()
          get {
            call.respondText("Hello, Nesty!")
          }
        }
      }
    }
  }.start(wait = true)
}

fun Route.rootDocumentation() {
  install(NotarizedRoute) {
    path = "/"
    get = KompendiumPlugins.GetInfo<Unit, Unit>(
      responseInfo = KompendiumPlugins.ResponseInfo(
        status = HttpStatusCode.OK,
        description = "Everything Works!"
      ),
      summary = "Doing a GET!"
    )
  }
}

fun Route.nestyDocumentation() {
  install(NotarizedRoute) {
    path = "/nesty"
  }
}

Route-level plugins are a killer feature. Going to make the code base so much cleaner! Essentially, you can now delegate a lot of the processing to individual routes, and have them each propagate just their own route metadata up to the application level plugin, which is what actually serializes the specification.

It also lets us ditch the notarizedX wrappers around the normal ktor routes, meaning that kompendium becomes essentially completely non-invasive, so it will be able to be applied to an existing API without modifying any of the existing code, purely additive.

And probably a bunch of other cool stuff I haven't even discovered yet

from kompendium.

Version 3 is stable enough that I went ahead and merged the PR and published the alpha release to maven central 🎉

This is still definitely an alpha release, and a number of things are missing

• Recursive types are broken Fixed
• Ktor Locations API is not yet supported Fixed
• Field level constraints (things like minimum: 0 etc) are broken
• Field name overrides (ie myAwesomeField -> my_awesome_field)

Also, there is still pretty much no documentation yet. The best reference is going to be the playground module at the moment.

Also, a couple modules were completely removed

• Swagger -> as mentioned above, they do not support OpenApi 3.1 yet.
• Annotations -> removed while I ponder a better strategy for things like field name overrides and constraints.
• Auth -> This is now part of core

Thanks to everyone who waited patiently for this, I had been waiting for the Jetbrains team to implement this like they said they would, but it's been long enough that I gave up hope and decided to just do it myself

from kompendium.

For the insanely foolish brave, I have gone ahead and published a snapshot of Kompendium V3 to GitHub packages https://github.com/bkbnio/kompendium/packages/779560 A ton of stuff is still broken, and practically the entire thing is undocumented, so this is not nearly fit for production at this point.

But... just in case your a tad mental and want to give it a go anyway, it is there :)

Short list of broken things

• Auth
• Locations API
• Polymorphic objects
• Generics
• Recursive objects
• Nested references
• Object constraints

Probably way more as well that I just haven't found yet 🙃

There is a super simple dummy app here that should give you a decent idea of how to get going

from kompendium.

I'm going to start a kompendium-2 library that will be compatible with Ktor 2... this library will be kept compatible with Ktor 1

from kompendium.

This is where I last heard the ktor team mention explicitly that they are working on swagger support https://youtu.be/mye9NjvxVSU?t=2412

from kompendium.

I've published a tentative list of things that would need to happen for a Kompendium V3.

https://github.com/orgs/bkbnio/projects/5

The breaking changes (as of now)

1. Moving to OpenAPI 3.1 (since this provides full Json Schema support, we can move the object serialization dialect to it's own module, and hopefully reduce a lot of the bugs that currently exist due to weird legacy openapi spec choices)
2. Support Ktor 2
3. Java 17 will become the baseline version as that is the most recent LTS
4. Swagger support will be dropped as they do not yet support OpenAPI 3.1 (see here)

from kompendium.

I'm going to start a kompendium-2 library that will be compatible with Ktor 2... this library will be kept compatible with Ktor 1

Hi @unredundant, is the kompenium-2 library already available?

from kompendium.

No, quite honestly this project is super lower on my priorities list. That, combined with that I've heard that the ktor team is working on their own openapi generator for v2 makes it super unlikely that there will be a kompendium port for ktor 2.

At least, one that I make ;)

from kompendium.

Hey @unredundant, I see there is a PR that is targeting to upgrade to Ktor support to 2.0.0.
I understand that this will not make this project run with the new release?
From the Ktor roadmap I don't see any actual timeline to get the Swagger UI support any time soon, maybe the next major release, but that is planned next year :(

from kompendium.

I can re-open this since there seems to be interest, but personally I won't be able to spend much (if any) time helping out with the effort at the moment.

My apologies 🙏

from kompendium.

@unredundant the same information (as on their road map) is that there are planning to bring support for SwaggerUI. But there is no timeline for it.

Do you know who as contributors could work on this?

from kompendium.

Need ktor 2.0 support badly

from kompendium.